Webhooks are HTTP callbacks from vendors (Stripe, GitHub, Slack). If you trust the body without verification, anyone who discovers your URL can forge events. Production setups verify HMAC signatures and defend against replay.
Typical headers
Vendors often send:
- A signature:
X-Signature,X-Hub-Signature-256, orStripe-Signature. - Sometimes a timestamp to bound freshness.
HMAC verification pattern
- Read the raw request body as bytes (do not re-serialize JSON differently).
- Concatenate per the provider spec (often
timestamp + "." + rawBody). - Compute
HMAC-SHA256(secret, payload)(or algorithm the vendor documents). - Compare with constant-time equality to the header value to avoid timing leaks.
Replay protection
Reject events older than a few minutes using the timestamp header. Store processed event_id (or hash of id + type) with TTL and skip duplicates.
Return fast
Acknowledge with 2xx quickly; queue heavy work asynchronously so the provider does not retry unnecessarily.
Mistakes teams make
- Parsing JSON before verifying, then hashing the wrong bytes.
- Logging full secrets or raw signing material.
- Using symmetric secrets in frontend code.