hooks.bot Docs / Svix / Standard Webhooks

Svix / Standard Webhooks webhook signature verification

Svix / Standard Webhooks signs each webhook and sends the digest in webhook-signature. When your check fails, one of a small number of steps is wrong — and guessing which is the slow way to find out. Paste the payload, the secret and the header block into the debugger and it rebuilds the signature every way it could plausibly have been made, then names the step that differs. It runs in your browser: the secret never leaves the page.

The scheme

Exactly what Svix / Standard Webhooks signs

Field	Value
Header	`webhook-signature`
Signed string	`{id}.{timestamp}.{body}`
Algorithm	HMAC-SHA-256
Digest encoding	base64
Key	whsec_… — the prefix is stripped and the remainder base64-decoded to key bytes.
Replay window	300s

Official reference: https://www.standardwebhooks.com/.

Causes

What actually goes wrong

Your framework parsed the body before you verified it. The signature covers the bytes on the wire. Once JSON has been parsed and re-serialized, whitespace and number formatting shift and the HMAC no longer matches. Read the raw body first: await req.text() in Next.js and Workers, express.raw() mounted before any express.json(), await request.body() in FastAPI, $request->getContent() in Laravel.
Whitespace on the secret. A trailing newline from a .env file or a Docker secret mounted as a file changes the key and nothing else. The debugger names this one specifically.
A stale timestamp. Svix / Standard Webhooks rejects anything outside a 300-second window even when the signature itself is correct. Replaying a request captured in your logs always trips this — it is expected, and it is not the bug you are chasing.
The wrong key derivation. whsec_… — the prefix is stripped and the remainder base64-decoded to key bytes.

Stripe and Svix both issue secrets that begin whsec_ and derive keys from them completely differently. Stripe uses the whole string, prefix included. Svix and Standard Webhooks strip the prefix and base64-decode the rest. This is the single commonest failure in the category.

Capture it

Get the real bytes, not a copy of a copy

If you are diagnosing from a logged payload you may be debugging the log rather than the webhook. Point Svix / Standard Webhooks at a disposable URL and work from what actually arrived:

curl -X POST https://www.hooks.bot/api/endpoints
# {"url":"https://www.hooks.bot/h/abc…"}

Paste that URL into your Svix / Standard Webhooks webhook settings, trigger an event, and the request appears at https://www.hooks.bot the moment it lands — headers, body and all. Press Diagnose this signature and add your secret.

Or let your agent do it

claude mcp add --transport http hooks-bot https://www.hooks.bot/mcp

Claude Code, Cursor and Codex can create the endpoint, block until the webhook lands, and diagnose it against the captured bytes without you copying anything.

Other providers

Stripe · GitHub · Shopify · Slack · Paddle Billing · Twilio