A webhook endpoint is a public URL that accepts POST requests from anyone on the internet. The signing secret is the only thing that distinguishes a genuine event from a forged one. Without verification, an attacker who guesses your endpoint can send you a payment_intent.succeeded and get free goods.
What the secret is used for
The sender computes HMAC-SHA256(secret, payload) and puts the result in a header. Your endpoint recomputes it and compares. Because HMAC requires the secret, only a party who holds it can produce a signature that verifies — and because HMAC covers the whole payload, changing a single byte invalidates it.
The secret is symmetric: both you and the sender hold the same value. That is why it must never appear in client-side code, and why leaking it is as serious as leaking an API key. See the webhook signature verifier for the exact bytes each provider signs.
Sizing
256 bits is right. HMAC-SHA256 processes keys longer than its 64-byte block size by hashing them first, so a 512-bit key is reduced to 256 bits before it does any work — you gain nothing and make the value harder to handle. Below 128 bits, an attacker who captures a payload and its signature could feasibly search for the key offline.
Generate two, always
Rotating a webhook secret is the one rotation that genuinely requires an overlap, because you cannot atomically update the sender's configuration and your verifier at the same instant. Any event in flight during the swap will be signed with the old secret and checked against the new one.
The procedure:
- Generate the new secret and add it to your verifier as a *second* accepted key.
- Deploy. Your endpoint now accepts signatures from either secret.
- Update the secret in the provider's dashboard.
- Watch until no event verifies against the old secret.
- Remove the old secret from your verifier.
Most providers support two active endpoint secrets for exactly this reason. Set the count to 2 above and you have both values before you start.
Verification mistakes that matter
- Verifying a re-serialised body. Frameworks that parse JSON before your handler runs give you an object, and
JSON.stringifyof that object is not byte-identical to what was sent. Capture the raw body. - Comparing with
==. A byte-by-byte comparison that returns early leaks the correct signature through timing. Use a constant-time comparison. - Ignoring the timestamp. Providers that include a timestamp in the signed payload do so to stop replay. If you do not check it, a captured request stays valid forever.
Frequently asked questions
What prefix should a webhook secret use?
whsec_ is the de facto convention, popularised by Stripe and adopted widely. Like any prefix it adds no entropy, but it lets secret scanners recognise the value and tells an engineer what they are looking at.
Can I use the same secret for multiple endpoints?
No. One secret per endpoint means a compromise is contained and you can rotate one endpoint without touching the others. Sharing a secret across endpoints also means a partner who legitimately holds one secret can forge events for all of them.
Do I need a webhook secret if my endpoint URL is unguessable?
Yes. An unguessable URL is a bearer credential in a query string: it appears in your logs, your reverse proxy's logs, and any Referer header. It also cannot be rotated without reconfiguring the sender, and it provides no integrity guarantee on the payload.
How do I test that verification actually works?
Use the Stripe and GitHub webhook sandbox with "tamper with the body" enabled. It produces a request whose signature no longer matches the payload. If your endpoint accepts it, you are not verifying the raw body.