Webhook Signature Verifier

Verify against the raw body

Providers sign the exact bytes they sent. Most frameworks parse JSON before your handler runs, and re-encoding it changes whitespace, key order and Unicode escaping, so the recomputed HMAC covers different bytes and never matches. Capturing the raw payload before any body-parsing middleware is the fix, and this single issue accounts for the majority of signature failures against otherwise correct code.

Each provider builds the signed string differently

Stripe signs a timestamp, a dot, and the payload, and sends multiple signatures in one header for key rotation. GitHub signs the body alone and prefixes the header value with sha256=. Others sign a concatenation of method, path, timestamp and body. Copying verification code between providers without reading their specification produces valid-looking failures.

Constant-time comparison

Comparing the computed and received signatures with ordinary string equality leaks information through timing, because comparison exits at the first differing byte. Every platform ships a constant-time comparison; the substitution is one line.

Timestamp tolerance stops replay

A captured valid request stays valid indefinitely unless the timestamp is checked. Reject anything outside roughly five minutes, and record processed event IDs so a duplicate delivery becomes a no-op — which also gives you the idempotency that at-least-once delivery requires.

Encoding and secret mistakes

Signatures may be hex or base64, and comparing one form against the other always fails. Secrets are often supplied with a prefix such as whsec_, and providers differ on whether the prefix is part of the key. A trailing newline from an environment file is another silent cause.