Webhook Signing & HMAC Verification Best Practices for Secure Delivery

Treat the signature as the gate in front of the rest of your webhook handler. Do not deserialize JSON, write to the database, call downstream APIs, or enqueue work until these checks pass.

1. Read the raw request body bytes exactly as received.
2. Extract the timestamp, key ID, and signature headers.
3. Reject stale timestamps before doing expensive work.
4. Look up the signing secret by key ID.
5. Rebuild the signed payload using the provider's documented format.
6. Compute HMAC-SHA256 and compare with a timing-safe function.
7. Reject duplicate event IDs or nonces inside the replay window.
8. Validate the payload schema and process idempotently.

This verifier assumes your framework gives you a Buffer containing the raw body. In Express, use express.raw() for the webhook route. In Next.js route handlers, call await request.arrayBuffer() before parsing JSON.

import crypto from "node:crypto";

const MAX_AGE_SECONDS = 300;

interface WebhookHeaders {
  "x-webhook-signature"?: string;
  "x-webhook-timestamp"?: string;
  "x-webhook-key-id"?: string;
}

export function verifyWebhookSignature(
  rawBody: Buffer,
  headers: WebhookHeaders,
  getSecret: (keyId: string) => string | undefined,
): boolean {
  const signatureHeader = headers["x-webhook-signature"];
  const timestampHeader = headers["x-webhook-timestamp"];
  const keyId = headers["x-webhook-key-id"];

  if (!signatureHeader || !timestampHeader || !keyId) return false;

  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) return false;

  const age = Math.abs(Date.now() / 1000 - timestamp);
  if (age > MAX_AGE_SECONDS) return false;

  const secret = getSecret(keyId);
  if (!secret) return false;

  const [, receivedHex] = signatureHeader.split("=", 2);
  if (!receivedHex) return false;

  const signedPayload = Buffer.concat([
    Buffer.from(`${timestampHeader}.`, "utf8"),
    rawBody,
  ]);

  const expectedHex = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  const received = Buffer.from(receivedHex, "hex");
  const expected = Buffer.from(expectedHex, "hex");

  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(received, expected);
}

Secret rotation should be boring and observable. Use a key ID so the receiver can pick the right secret without trying every value, then keep a short grace window for retries signed with the previous key.

• Store signing secrets in a secret manager, not in source code.
• Issue every active secret with a stable kid value.
• Accept current and previous secrets during the rotation overlap.
• Log the key ID that verified each delivery so old-key traffic is visible.
• Remove expired keys after retry traffic drains and alerts stay quiet.

Signature bugs usually come from framework body parsing, wrong secrets, stale clocks, or retry paths that bypass verification. Test happy-path signatures, modified payloads, stale timestamps, wrong key IDs, and duplicate event IDs before enabling production traffic.

Use Hooklistener to capture a real delivery, inspect the raw headers, replay it to your local handler, and compare how your app responds to valid and intentionally broken signatures.