Home / Knowledge hub / Webhook signature
Knowledge hub
Webhook signature
A check that an incoming webhook really came from the service it claims.
What it means
A webhook is a request that another service sends to your app when something happens, such as a payment succeeding. Because the address is public, anyone could send a request to it. A webhook signature is a value, usually an HMAC, that lets you check the sender.
The sender computes the signature over the message using a secret that only you and they share. You compute it again on your side. If the two match, the message is genuine and unchanged. If they differ, you ignore it.
Why it matters
Without that check, anyone who finds your webhook address can post a fake event: a payment marked as paid, a subscription upgraded, an order released. Nothing is hacked in the usual sense. Your own app is simply told something false and acts on it.
The cost lands in the same places as any payment fraud: goods shipped without money, access granted for free, and records that no longer match the provider's. These forged events also look like normal traffic in your logs, so finance usually finds them first.
How it shows up
You meet signatures in payment providers, source code hosts and messaging tools, each with its own header and scheme. Providers such as Stripe publish a verification routine that checks the signature and a timestamp. Common mistakes are skipping the check, comparing the signature as plain text, and verifying a re-formatted body instead of the raw bytes.
Do the check on the exact raw body, use a constant-time comparison, reject old timestamps to block a replay, and keep the secret out of code, as in secrets management. Test by sending an event with a wrong signature, then an old one.
Questions people ask
Webhook signature, answered
What is the difference between a webhook secret and an API key?
An API key lets you call someone else's service. A webhook secret lets you verify that calls to you came from them.
They are separate secrets and should be stored and rotated separately.
Why must the raw body be used for verification?
Because the signature covers the exact bytes sent. If your framework parses and re-serialises the JSON first, spacing or key order may change and the check fails, or worse, gets disabled.
Capture the raw body before any parsing.
Can't we just allow the provider's IP addresses?
It helps as an extra layer, but addresses change and lists get out of date. It also gives no proof the content was not altered.
Use the signature as the main check.
How do we stop replayed webhooks?
Providers usually include a timestamp in what is signed. Reject events older than a short window, and record event ids you have already handled.
That way a captured genuine message cannot be sent again.
How do we test our webhook handler?
Send an event with no signature, with a wrong one, and with an old timestamp. All three should be refused without changing any data.
Then send the same valid event twice and confirm it only takes effect once.
Related
Terms that sit next to this one
Webhook
A URL you hand to another service so it can call you when something happens.
HMAC
A hash mixed with a secret key, proving a message is unchanged and from the key holder.
Replay attack
Capturing a valid request and sending it again to get the same result twice.
Payment fraud
Using stolen or fake payment details to buy from your business.
Secrets management
Keeping keys, passwords and tokens out of code and in a vault.
Would your app believe a fake event?
A webhook endpoint that trusts any caller will act on forged events. We send unsigned, altered and replayed events to your handlers and report exactly what your app did with them. Book a pilot on one app.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.