Verifying webhook signatures with HMAC: a practical guide

POST /webhooks/email HTTP/1.1
Content-Type: application/json
X-Signature: sha256=5d2f1c...
X-Timestamp: 1790553600

{"event":"message.bounced","message_id":"msg_01J8Z...","to":"[email protected]"}

Implementations#

The examples assume the provider signs the string "{timestamp}.{raw_body}" with HMAC-SHA256 and sends the hex digest as sha256=<hex>. Adapt the signed string to your provider's scheme.

Node.js#

import crypto from "node:crypto";

export function verify(rawBody, sigHeader, tsHeader, secret, toleranceSec = 300) {
  const ts = Number(tsHeader);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${ts}.`).update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(sigHeader || ""));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

With Express, capture the raw body for the webhook route using express.raw({ type: "application/json" }) rather than the JSON parser.

Python#

import hashlib, hmac, time

def verify(raw_body: bytes, sig_header: str, ts_header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        ts = int(ts_header)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    expected = "sha256=" + mac.hexdigest()
    return hmac.compare_digest(expected, sig_header or "")

In Flask, use request.get_data(); in Django, request.body; in FastAPI, await request.body(), all before parsing JSON.

Go#

func verify(body []byte, sigHeader, tsHeader, secret string, tolerance time.Duration) bool {
	ts, err := strconv.ParseInt(tsHeader, 10, 64)
	if err != nil {
		return false
	}
	if d := time.Since(time.Unix(ts, 0)); d > tolerance || d < -tolerance {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(tsHeader + "."))
	mac.Write(body)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(sigHeader))
}

Read the body once with io.ReadAll(r.Body), verify, then unmarshal from the same byte slice.

Testing your verifier#

Signature code is easy to get almost right, so test it deliberately rather than waiting for production traffic:

• A known-good fixture. Capture one real delivery (body, headers and the secret from a test endpoint) and assert that your function returns true for it.
• A tampered body. Change one character of the payload and assert false.
• A wrong secret. Assert false.
• A stale timestamp. Shift the timestamp outside the tolerance window, recompute a valid signature for it, and assert false. This proves the timestamp check runs even when the signature is otherwise correct.
• A missing or malformed header. Assert false without throwing an unhandled exception.
• The framework path. Send a request through your real routing and middleware in an integration test, which catches the most common production bug: a JSON parser consuming the body before your verifier sees the raw bytes.

Many providers also offer a "send test event" button in their dashboard. Use it after every deploy that touches the webhook route.

Rotating the secret without downtime#

Secrets need rotation when staff change, when one may have leaked, or on a schedule. Many providers let an endpoint have two active secrets during a transition, and some send multiple signatures in one header. Your verifier should accept a list of secrets and pass if any of them matches:

1. Add the new secret to your configuration alongside the old one.
2. Rotate the secret at the provider.
3. Once all deliveries verify with the new secret, remove the old one.

Other hardening worth doing#

• HTTPS only. Signatures prove origin and integrity, but the payload may contain personal data such as email addresses.
• Respond quickly. Verify, persist the event, return 2xx, and process asynchronously. Slow handlers cause provider timeouts and retries.
• Return 401 or 400 on verification failure, and log it with the source IP, but never log the secret or the full computed signature.
• Do not use IP allowlists as the only check. They are a reasonable extra layer if the provider publishes stable ranges, but they are brittle and do not protect the payload's integrity.
• Keep the secret out of source control, in the same secret store as your API keys.

Verification checklist#

• Raw body captured before JSON parsing.
• HMAC computed over exactly what the provider signs.
• Constant-time comparison.
• Signed timestamp checked against a tolerance window.
• Delivery IDs recorded to drop replays and duplicates.
• Multiple secrets supported for rotation.
• Fast 2xx response with asynchronous processing.

Key takeaways#

• Webhook endpoints are public, so every delivery must be verified before it changes state.
• Verify HMAC over the raw body, not a re-serialized object.
• Use timingSafeEqual, hmac.compare_digest or hmac.Equal for comparison.
• Reject stale timestamps and duplicate delivery IDs to limit replay.
• Support two secrets at once so rotation never breaks deliveries.