Verify a Webhook Signature

When you pass a webhookUrl to Submit, Dango sends a single signed POST once every line in the batch is enriched. The body is minimal:

{
  "project_id": "aB3xK9",
  "event": "enrichment.completed",
  "status": "completed",
  "counts": { "total": 100, "enriched": 100, "failed": 0 }
}

The webhook is only a notification: call Export a CSV to fetch the enriched result.

Signature scheme

Every delivery carries two headers:

X-Dango-Signature: sha256=<hex>: the HMAC-SHA256 of your organization’s webhook secret over the string "{timestamp}.{body}", hex-encoded.
X-Dango-Timestamp: <unix-seconds>: the same timestamp, for anti-replay.

To verify an inbound request:

Read the raw request body exactly as received. Do not parse and re-serialize it, or the bytes (and the signature) will differ.
Recompute HMAC-SHA256(secret, "{timestamp}.{rawBody}") and hex-encode it.
Compare it to the header value using a constant-time comparison.
Reject the request if X-Dango-Timestamp is too old (here, 5 minutes) to prevent replay.

The secret is per-organization; keep it in an environment variable (DANGO_WEBHOOK_SECRET below), never in source.

Examples

#!/usr/bin/env bash
# Reads the raw body on stdin. Args: timestamp, signature header value.
set -euo pipefail

RAW_BODY="$(cat)"
TIMESTAMP="$1"
SIGNATURE="${2#sha256=}"   # strip the "sha256=" prefix

# Anti-replay: reject if older than 5 minutes.
NOW=$(date +%s)
if (( NOW - TIMESTAMP > 300 )); then
  echo "stale timestamp" >&2
  exit 1
fi

EXPECTED=$(printf '%s.%s' "$TIMESTAMP" "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$DANGO_WEBHOOK_SECRET" -r \
  | cut -d' ' -f1)

# Constant-time-ish compare via HMAC of both sides.
if [[ "$EXPECTED" == "$SIGNATURE" ]]; then
  echo "valid"
else
  echo "invalid" >&2
  exit 1
fi

import hashlib
import hmac
import os
import time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["DANGO_WEBHOOK_SECRET"].encode("utf-8")

@app.post("/hooks/dango")
def dango_webhook():
    raw_body = request.get_data()  # raw bytes, not request.json
    timestamp = request.headers.get("X-Dango-Timestamp", "")
    header = request.headers.get("X-Dango-Signature", "")

    # Anti-replay: reject if older than 5 minutes.
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        abort(400, "stale timestamp")

    signed = f"{timestamp}.".encode("utf-8") + raw_body
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
    received = header.removeprefix("sha256=")

    if not hmac.compare_digest(expected, received):
        abort(401, "bad signature")

    # Signature verified, parse the body and enqueue an export.
    return "", 204

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.DANGO_WEBHOOK_SECRET!;

// Capture the raw body (express.json() would discard the exact bytes).
app.post(
  "/hooks/dango",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody: Buffer = req.body;
    const timestamp = String(req.header("X-Dango-Timestamp") ?? "");
    const header = String(req.header("X-Dango-Signature") ?? "");

    // Anti-replay: reject if older than 5 minutes.
    const ts = Number(timestamp);
    if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) {
      return res.status(400).send("stale timestamp");
    }

    const expected = createHmac("sha256", SECRET)
      .update(`${timestamp}.`)
      .update(rawBody)
      .digest("hex");
    const received = header.replace(/^sha256=/, "");

    const a = Buffer.from(expected);
    const b = Buffer.from(received);
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.status(401).send("bad signature");
    }

    // Signature verified, parse rawBody and enqueue an export.
    res.status(204).end();
  },
);

app.listen(3000);

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

var secret = []byte(os.Getenv("DANGO_WEBHOOK_SECRET"))

func dangoWebhook(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body) // raw bytes, before any JSON decode
	if err != nil {
		http.Error(w, "read error", http.StatusBadRequest)
		return
	}
	timestamp := r.Header.Get("X-Dango-Timestamp")
	header := r.Header.Get("X-Dango-Signature")

	// Anti-replay: reject if older than 5 minutes.
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || time.Since(time.Unix(ts, 0)) > 5*time.Minute {
		http.Error(w, "stale timestamp", http.StatusBadRequest)
		return
	}

	mac := hmac.New(sha256.New, secret)
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(header, "sha256=")

	if !hmac.Equal([]byte(expected), []byte(received)) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}

	// Signature verified, parse rawBody and enqueue an export.
	w.WriteHeader(http.StatusNoContent)
}

func main() {
	http.HandleFunc("/hooks/dango", dangoWebhook)
	http.ListenAndServe(":3000", nil)
}

Export a CSV