Verify signatures - Traddal Developers

Every delivery carries these headers:

Header	Contents
`X-Traddal-Event`	The event type (`consignment.created`, …)
`X-Traddal-Delivery`	Unique delivery ID — dedupe key
`X-Traddal-Timestamp`	Unix timestamp of the send
`X-Traddal-Signature`	`v1=<hex HMAC>`

The signature is an HMAC-SHA256 over the timestamp and the raw request body, keyed with your endpoint’s secret (whsec_…, shown on the Developers page):

hex = HMAC_SHA256(secret, "{X-Traddal-Timestamp}.{rawBody}")

Reject the delivery when the recomputed HMAC differs, or when the timestamp is older than a few minutes (replay guard).

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

export function verifyTraddalWebhook(
  rawBody: string,
  headers: Record<string, string>,
  secret: string,
): boolean {
  const timestamp = headers["x-traddal-timestamp"];
  const signature = headers["x-traddal-signature"]; // "v1=<hex>"
  if (!timestamp || !signature?.startsWith("v1=")) return false;

  // Replay guard: reject anything older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const given = signature.slice(3);
  return (
    expected.length === given.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(given))
  );
}

import hashlib, hmac, time

def verify_traddal_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    timestamp = headers.get("x-traddal-timestamp", "")
    signature = headers.get("x-traddal-signature", "")
    if not timestamp or not signature.startswith("v1="):
        return False
    if abs(time.time() - float(timestamp)) > 300:  # replay guard
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature[3:])

Compute the HMAC over the raw body bytes exactly as received. Parsing and re-serializing the JSON will change key order or whitespace and break the signature.

Rotating the secret (Developers page or POST /admin/api/v1/settings/webhooks/{id}/rotate-secret) invalidates old signatures immediately.