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-Signature: t=1713745909,v1=2b8f5cdb7e0ea7c3f2a4b6e1d7c9f83a2a4b6e1d7c9f83ab1c9d6e4f2a0b8c7d- t
- The unix timestamp (seconds) at which we signed the payload. Your receiver should reject
deliveries where
|now − t| > 300seconds to defeat replays. - v1
- Lower-case hex of
HMAC-SHA256(signing_secret, `${t}.${signedPayload}`). For POST,signedPayloadis the raw body. For GET, it is the canonical query string.
The contract
Verification rules.
These rules are language-agnostic. Every reference implementation below is the same check expressed in that language’s idioms.
- 01 For POST, read the raw request body exactly as received. Re-serializing parsed JSON almost always breaks the signature because key order and whitespace change.
- 02 For GET, build the canonical query string by sorting query entries by key, then value, and URL-encoding with URLSearchParams.
- 03 Parse X-Webhook-Signature into its timestamp (t=) and signature (v1=) parts. Treat anything else as invalid.
- 04 Compute 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.
- 05 Reject stale timestamps. Five minutes is a reasonable default — anything older is almost certainly a replay.
- 06 Compare 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.
// 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");
}
}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.