Webhook signatures prove an inbound event came from the service you named in the docs, not from someone who found a public URL. Without that check, a webhook is an open POST that can create invoices, reset passwords, or mark orders paid.
Treat the signature as part of the contract, the same way you treat auth on your own API. If the check fails, drop the request before any business logic runs.
What Signatures Protect
They stop forged events, replayed captures, and partners who paste a sample body into curl and hit your production URL by mistake. A per-partner secret plus a timestamp also limits how long a stolen payload stays useful.
They do not replace authentication on the routes your app calls out. They answer one question: did this sender prove they hold the secret you issued?
Design Choices That Matter
Sign the raw body bytes, not a re-serialized JSON object. Whitespace and key order will break a check that looks fine in a unit test and fails once a real partner sends traffic.
- Store a separate signing secret per partner or endpoint, not one global string reused across every integration.
- Include a timestamp in the signed string and reject events older than a short window, often two to five minutes.
- Compare signatures with a constant-time function so timing does not leak which bytes matched.
- Version the header. A
v1=hex value today can sit beside v2= later without a hard cutover. - Log the partner id, endpoint, and failure reason. Do not log the secret or the full signature.
Prefer HMAC-SHA256 over a hash you invented. Publish the header name, the encoding (hex or base64), and one worked example with a known secret and body.
Common Mistakes
Teams ship the endpoint first and add the check after the first bad event. That window is enough for a forged payment webhook or a fake
user.deleted callback.
- Parsing JSON, then signing the parsed object, which changes field order. Honest senders fail, or the exception handler skips the check entirely.
- Accepting a missing signature header outside production, then leaving the bypass on in a staging box that shares a database.
- Returning a detailed 401 that echoes the expected format and a hash of the body.
- Rotating the secret with no overlap, so every in-flight retry fails until support notices the queue.
- Libraries that “verify” by checking the header is non-empty.
Safe Rollout
If the endpoint already has traffic, start in observe mode. Count mismatches per partner, fix clock skew and encoding bugs, then reject. New endpoints should reject from the first request.
- Publish a test secret and a fixture body in the partner docs.
- Keep the previous secret valid for a short overlap when you rotate.
- Alert on a sudden rise in signature failures for one partner, and on any partner with zero failures after a secret change. They may have stopped sending, or they never verified at all.
- Keep a runbook: who can rotate a secret, how to replay a failed event, and which dashboard shows recovery.
What to Tell Partners
Put the header names, the signed string, and a copy-paste example next to the webhook URL. Ask them to send the same raw body they signed, and to retry with the same event id so you can dedupe.
- A clear example cuts tickets from integrators who almost got the bytes right.
- Deduping on an event id stops a valid retry from double-charging or double-emailing.
- Signature checks sit beside auth, rate limits, and allowlists. They do not replace them.
Build the check before the first partner goes live, document the bytes you sign, and treat a sustained failure spike as an incident, not a noisy log line.