hooks.bot Docs / Twilio

Twilio webhook signature verification

Twilio signs each webhook and sends the digest in X-Twilio-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 Twilio signs

Field	Value
Header	`X-Twilio-Signature`
Signed string	`URL + sorted POST params`
Algorithm	HMAC-SHA-1
Digest encoding	base64
Key	Your account Auth Token — not an API key secret.
Replay window	not timestamped

Official reference: https://www.twilio.com/docs/usage/security#validating-requests.

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.
The wrong credential entirely. Twilio issues several, and a Twilio API key SID will all fail here. The debugger recognises each by its prefix and says so before it tries anything else.
Signing the body. Twilio signs the full request URL plus your sorted POST parameters, not the payload. If your handler sits behind a proxy that rewrites the scheme or the host, the URL you rebuild is not the URL Twilio signed.
The wrong key derivation. Your account Auth Token — not an API key secret.

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 Twilio 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 Twilio 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 · Svix / Standard Webhooks · Shopify · Slack · Paddle Billing