How to Secure a Webhook Endpoint (HMAC + Replay Protection)

Why webhooks need this

A webhook URL is public, so anyone can POST to it. Without verification, an attacker can forge events (fake a payment, trigger actions). The standard defense (Stripe, GitHub, Shopify all do it): the sender signs each request with a shared secret; you verify the signature before trusting the payload.

The signature header

Senders include a header like:

X-Webhook-Signature: t=1700000000,v1=5257a869e7 ...

t is the timestamp; v1 is HMAC_SHA256(secret, "<t>.<raw_body>"). You recompute it and compare.

Verify it

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts["t"], parts["v1"]

    # 1. Replay protection: reject stamps outside the tolerance window
    if abs(time.time() - int(t)) > tolerance:
        return False

    # 2. Recompute the HMAC over "<t>.<raw_body>"
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    # 3. Constant-time compare (no early-exit timing leak)
    return hmac.compare_digest(expected, sig)

The three things that make it secure

1. Sign the raw body, not the parsed JSON. Re-serializing changes bytes (key order, spacing) and breaks the signature - verify against the exact bytes received.
2. Timestamp + tolerance = replay protection. Without checking t, an attacker can resend a valid captured request forever. Reject anything older than ~5 minutes.
3. Constant-time comparison. hmac.compare_digest (not ==) so an attacker can't learn the signature byte-by-byte from response timing.

Operational notes

• Return 2xx fast, process async. Acknowledge quickly so the sender doesn't retry; do the real work in a queue. Combine with idempotency (dedupe on the event id) since senders retry and deliver at-least-once.
• Rotate the secret if it leaks; support two valid secrets briefly during rotation.