Verifying webhook signatures without losing a day to it

An endpoint that accepts unsigned webhooks is a public API that creates orders and marks invoices paid. Verification is ten lines, and eight of them are about getting the raw request body.

What a signature actually proves

The provider computes an HMAC over the request body using a secret you both hold, and sends the result in a header. You recompute it and compare. If the values match, two things are true: the body was produced by someone holding the secret, and nothing changed it in transit.

Three things are not true. The payload is not confidential, so you still need TLS. The request is not necessarily recent, so you still need a timestamp check. And the event is not necessarily new, so you still need idempotency on the event id. Teams routinely ship the first check and skip the other two, which leaves a valid captured request replayable for as long as the attacker likes.

HMAC is the right primitive here and not a plain hash. sha256(secret + body) is vulnerable to length extension on Merkle-Damgård constructions, which is precisely the class of mistake HMAC's inner and outer padding was designed to remove. If you want the mechanics rather than the recipe, the HMAC generator computes the same thing your library does and shows the hex and base64 forms side by side, which turns out to be the fastest way to find out which of the two your provider actually wanted.

The raw body problem

This is the cause of the overwhelming majority of "signature mismatch" tickets, and it has nothing to do with cryptography.

The provider signed a specific byte sequence. Your framework parsed that sequence into an object before your handler ran. When you then hash JSON.stringify(req.body), you are hashing a reconstruction, and reconstructions differ in ways that are invisible on screen:

• Key order changes if anything normalised the object.
• Whitespace disappears. Stripe sends compact JSON, some providers send pretty-printed payloads with two-space indentation.
• Unicode escaping flips. "café" and "café" are the same string and different bytes.
• A trailing newline is dropped, or added.
• Numbers get reformatted. 1.0 becomes 1, and an amount in a big-integer id loses precision entirely.

Every one of those changes the HMAC completely. So the rule is: capture the bytes before anything parses them, verify against those bytes, and only then parse. In Express that means express.raw({ type: 'application/json' }) on the webhook route, mounted before the global JSON parser. In the Next.js App Router it means await req.text() as the first line of the route handler. In Django it is request.body, untouched by any earlier access to request.POST.

One symptom worth recognising: verification that works in local testing and fails in production usually means something in production is rewriting the body. A gateway that decompresses gzip, a WAF that normalises unicode, a proxy that re-serialises JSON. Log the received byte length next to the length the provider reports and the difference shows up immediately.

Five providers, five schemes

There is no standard, so every integration is a small reading exercise. The differences that matter are which bytes go into the HMAC, which hash, and which encoding comes out.

Three traps hide in that table. Stripe's header is a list, not a value: t=1739...,v1=5257a869..., and you have to split it and use the timestamp as part of the signed string, not just as metadata. GitHub still sends the old SHA-1 X-Hub-Signature alongside the SHA-256 one for compatibility, and code that grabs the first matching header sometimes ends up verifying the weaker of the two. Twilio does not sign the body at all in the classic form-encoded case: it signs the full request URL with the sorted parameters appended, which means a reverse proxy that rewrites the host or drops the port breaks verification while the body arrives perfectly intact.

Base64 versus hex is worth one sentence because it wastes so much time: a 64-character hex string and a 44-character base64 string can be the same 32 bytes. If your value looks right but never matches, decode both and compare the bytes, which is one paste into the base64 encoder.

There is a convergence effort. The Standard Webhooks specification, used by Svix and adopted by a growing number of APIs, defines webhook-id, webhook-timestamp and webhook-signature headers with the signed content id.timestamp.body. If you are designing outbound webhooks rather than consuming them, implementing that is more useful than inventing a sixth scheme.

Timestamps and the replay window

A signature stays valid forever, which means a captured request is a reusable one. If the payload says "subscription renewed", replaying it a hundred times can extend an account for a hundred months, depending on how naive the handler is.

The defence is a timestamp inside the signed content, which is exactly why Stripe and Slack put it there. Your check has two parts: verify the signature over timestamp + separator + body, then reject the request if the timestamp is more than a few minutes old. Five minutes is the conventional tolerance in both providers' libraries. Because the timestamp is inside the HMAC input, it cannot be edited without breaking the signature.

For providers that sign only the body, the timestamp defence is unavailable and idempotency has to do the whole job: store the event id, ignore ids you have already processed, keep the store for longer than the provider's retry schedule. Do that anyway, because at-least-once delivery means duplicates arrive without an attacker.

Compare signatures with a constant-time function, crypto.timingSafeEqual in Node or hmac.compare_digest in Python. Wrap it so that a length mismatch returns false instead of throwing, which is the usual reason a "timing-safe" comparison ends up inside a try block that swallows the failure.

Rotating a signing secret

Webhook secrets leak the same way every other secret leaks: a screenshot, a committed .env, a HAR file attached to a support ticket. Rotation should be a routine operation, not an incident procedure, and it only works if the receiver can hold two secrets at once.

The pattern: verify against the new secret, fall back to the old one on failure, log which one matched, and remove the old secret once the log stops mentioning it. Stripe builds this in by letting an endpoint carry a second signing secret with an expiry. Where the provider does not, an array of secrets in your config does the same job.

Store the secret where the rest of your secrets live, not in the repository. A webhook secret in a public commit is one of the fastest-scanned patterns on GitHub, and the usual way it lands there is a .env that .gitignore never actually ignored, because the file had already been tracked before the rule was added. Rotating the secret is the only real fix once it has been pushed; deleting the commit is not.

Debugging a mismatch

When the values disagree, work down this list in order. It is the order of how often each one is the answer.

1. Are you hashing the raw bytes, or a reserialised object? Log rawBody.length and compare with Content-Length.
2. Right secret for the right endpoint? Providers issue one per endpoint, and the test-mode and live-mode secrets differ. Stripe's are prefixed whsec_ for both, so they look identical at a glance.
3. Right signed content? Stripe and Slack prepend the timestamp, GitHub and Shopify do not.
4. Right encoding? Hex against base64 is the classic, and comparing a string with a Buffer silently fails in Node.
5. Is something between the client and your handler modifying the body? Compare a hash of what you received with what the provider logged as sent.
6. Is the header being read case-correctly, and is it the header you think? GitHub's SHA-1 and SHA-256 headers differ by a suffix.

Two tools shorten this loop. Paste the payload into the webhook payload viewer to read the event structure and the headers without piping it through your own code, and compute the expected HMAC by hand in the HMAC generator with the exact string you believe is being signed. If the manual result matches the header, the bug is in your body handling; if it does not, the bug is in your signed-content assumption. That single split saves most of the afternoon.

What the endpoint should do

Verification is only the front door. The handler around it has its own set of rules, most of them learned the hard way.

• Verify before parsing, and before touching a database.
• Return quickly. Most providers time out between 5 and 30 seconds and treat a slow response as a failure, so queue the work and return 200 immediately. Stripe documents this explicitly as the reason for delivery retries.
• Return 400 on a bad signature, 200 on an event you choose to ignore. A 500 puts you in the retry schedule, which is a self-inflicted denial of service when a deploy breaks the handler for ten minutes.
• Make the handler idempotent on the event id. Retries are normal, and two identical "payment succeeded" events must not ship two orders.
• Log the event id, type and verification result. Never log the signature, the secret or the full payload, since payloads carry customer data.
• Do not trust the payload's own claim about state. For anything that moves money, treat the webhook as a notification and re-read the object from the provider's API before acting on it.

The last one is the habit that ages best. A signed webhook tells you something happened; the provider's API tells you what is true now, and those two answers diverge more often than the payload suggests.

Signature verification questions