Signature Verification

Trust the payload after you've verified it — not before.

Your endpoint signing secret never leaves your server, never leaves ours. Every delivery is signed with HMAC-SHA256 and a unix timestamp. POST signs the raw body; GET signs the canonical query string.

One header, two fields

How a signature is built.

Every delivery carries a single X-Webhook-Signature header. It’s a comma-separated pair: a unix timestamp and the hex HMAC-SHA256 of `${timestamp}.${signedPayload}`.

X-Webhook-Signatureone header on every delivery

X-Webhook-Signature: t=1713745909,v1=2b8f5cdb7e0ea7c3f2a4b6e1d7c9f83a2a4b6e1d7c9f83ab1c9d6e4f2a0b8c7d

t: The unix timestamp (seconds) at which we signed the payload. Your receiver should reject deliveries where |now − t| > 300 seconds to defeat replays.
v1: Lower-case hex of HMAC-SHA256(signing_secret, `$${t}.$${signedPayload}`). For POST, signedPayload is the raw body. For GET, it is the canonical query string.

The invariant

If the timestamp and signed payload haven't changed since we signed them, your HMAC will match ours byte for byte.

The contract

Verification rules.

These rules are language-agnostic. Every reference implementation below is the same check expressed in that language’s idioms.

01For POST, read the raw request body exactly as received. Re-serializing parsed JSON almost always breaks the signature because key order and whitespace change.
02For GET, build the canonical query string by sorting query entries by key, then value, and URL-encoding with URLSearchParams.
03Parse X-Webhook-Signature into its timestamp (t=) and signature (v1=) parts. Treat anything else as invalid.
04Compute HMAC-SHA256 over `${timestamp}.${signedPayload}` using your endpoint signing secret. The signed payload is the raw body for POST and the canonical query string for GET.
05Reject stale timestamps. Five minutes is a reasonable default — anything older is almost certainly a replay.
06Compare the computed signature to the received one with a constant-time equality check. Never use a plain `===`.

Pick your stack

Reference implementations.

Switch languages with the tabs. The algorithm is identical: parse, age-check, HMAC-SHA256, constant-time compare.

verify.(ts|py|php|go)

// Node.js / TypeScript — works in Next.js, Express, Fastify, Bun, Hono.
import crypto from "node:crypto";
 
export function verifyTradingLayerWebhook({
  rawBody,
  signatureHeader,
  secret,
  toleranceSeconds = 300,
}: {
  rawBody: string;
  signatureHeader: string | null;
  secret: string;
  toleranceSeconds?: number;
}) {
  if (!signatureHeader) {
    throw new Error("Missing X-Webhook-Signature header");
  }
 
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => {
      const [key, value] = part.split("=");
      return [key, value];
    }),
  );
 
  const timestamp = Number(parts.t);
  const receivedSignature = parts.v1;
 
  if (!timestamp || !receivedSignature) {
    throw new Error("Invalid signature header");
  }
 
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) {
    throw new Error("Webhook timestamp is too old");
  }
 
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
 
  const expectedBuffer = Buffer.from(expectedSignature, "hex");
  const receivedBuffer = Buffer.from(receivedSignature, "hex");
 
  if (
    expectedBuffer.length !== receivedBuffer.length ||
    !crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
  ) {
    throw new Error("Invalid signature");
  }
}

Why HMAC-SHA256 and not a JWT?

HMAC lets you verify integrity and origin without standing up any PKI. Your signing secret is a symmetric secret that both sides already have; a JWT would just encode the same HMAC with an extra envelope. The signed string intentionally includes the timestamp so that replaying an old, valid payload is rejected by the age check.

Things that bite teams

Common pitfalls.

Nearly every 'signature doesn't match' support ticket lands on one of these five. Rule them out in this order.

01
Parsed-body leak
You called req.json() (or bodyParser.json()) before capturing the raw body. Fix: capture the raw body first, then verify, then parse.
02
Re-serialized JSON
You pretty-printed the payload for logging, then re-signed the pretty version. Always verify against the bytes we delivered, not a reformatted copy.
03
Wrong secret
You copied the dashboard secret for a different endpoint, or pasted with a trailing newline. Secrets are per-endpoint — rotate if you ever suspect drift.
04
Clock skew
Your host drifted more than 5 minutes from UTC. Enable NTP; relax the tolerance only if you understand the replay trade-off.
05
Non-constant-time compare
You used expected === received. In a well-behaved receiver this doesn't fail verification — but it leaks timing. Always use the language's timingSafeEqual / hash_equals / hmac.Equal equivalent.

PreviousEvent types NextOverview

// Node.js / TypeScript — works in Next.js, Express, Fastify, Bun, Hono. import crypto from "node:crypto"; export function verifyTradingLayerWebhook({ rawBody, signatureHeader, secret, toleranceSeconds = 300, }: { rawBody: string; signatureHeader: string | null; secret: string; toleranceSeconds?: number; }) { if (!signatureHeader) { throw new Error("Missing X-Webhook-Signature header"); } const parts = Object.fromEntries( signatureHeader.split(",").map((part) => { const [key, value] = part.split("="); return [key, value]; }), ); const timestamp = Number(parts.t); const receivedSignature = parts.v1; if (!timestamp || !receivedSignature) { throw new Error("Invalid signature header"); } const now = Math.floor(Date.now() / 1000); if (Math.abs(now - timestamp) > toleranceSeconds) { throw new Error("Webhook timestamp is too old"); } const expectedSignature = crypto .createHmac("sha256", secret) .update(`${timestamp}.${rawBody}`) .digest("hex"); const expectedBuffer = Buffer.from(expectedSignature, "hex"); const receivedBuffer = Buffer.from(receivedSignature, "hex"); if ( expectedBuffer.length !== receivedBuffer.length || !crypto.timingSafeEqual(expectedBuffer, receivedBuffer) ) { throw new Error("Invalid signature"); } }