Twilio webhooks
How to Test Twilio Webhooks (and Verify X-Twilio-Signature)
Twilio calls your URL when a message arrives or a call starts, and reads your reply to decide what to do next. Its signature scheme is different from most.
Capture a real Twilio webhook in a minute
- Get a URL. Use the button on this page. It opens the inspector with a fresh URL that is ready to receive.
- Give it to Twilio. In the Twilio Console, open the phone number's configuration and paste the URL under A message comes in or A call comes in.
- Trigger an event. The request appears in the inspector as it arrives, with Twilio recognised and the event name shown.
- Check the signature. Open Verify signature, paste your secret and confirm the request is genuine. The check runs in your browser.
What Twilio sends
Incoming message and call webhooks are form-encoded POST requests by default, with fields such as From, To, Body and MessageSid. The inspector shows form bodies as a table of fields.
| Header | Meaning |
|---|---|
X-Twilio-Signature | Base64-encoded HMAC-SHA1 of the URL and the request parameters. |
Content-Type | application/x-www-form-urlencoded for most webhooks. |
I-Twilio-Idempotency-Token | Stays the same across retries of one event. |
Why the signature includes the URL
Twilio does not sign the raw body. It signs a string built like this:
- Start with the full URL Twilio requested, including any query string.
- For a form-encoded
POST, sort the parameters by name and append each name immediately followed by its value. - Compute an HMAC-SHA1 of that string with your account's auth token, and base64-encode it.
import crypto from "node:crypto";
export function verifyTwilio(url, params, header, authToken) {
const data = Object.keys(params)
.sort()
.reduce((acc, key) => acc + key + params[key], url);
const expected = crypto
.createHmac("sha1", authToken)
.update(Buffer.from(data, "utf-8"))
.digest("base64");
const received = header ?? "";
return received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}In production, the official helper library's validateRequest handles the edge cases for you.
http instead of https, a different host, a missing port. Rebuild the public URL before verifying, or verification will fail on valid requests.Replying with TwiML
Twilio reads the response body as instructions. To reply to an SMS from a test endpoint, set the response on your webhook.stream URL to content type text/xml with a body like this:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Message>Got it, {{body.From | escape}}</Message>
</Response>The template inserts the sender's number from the incoming form fields, so you can test a full round trip without writing any code.
What Twilio expects back
- A response within about 15 seconds. After that Twilio gives up on the request.
- Valid TwiML or an empty 2xx. An empty
<Response/>means "do nothing".
Frequently asked questions
Why is my Twilio signature invalid behind a proxy?
Twilio signs the exact public URL it requested. Behind a proxy your application often sees a different scheme or host. Reconstruct the original URL, typically from the X-Forwarded-Proto and Host headers, before validating.
Does Twilio sign the request body?
For form-encoded webhooks it signs the URL plus the sorted parameters rather than the raw body. For JSON webhooks, the body is covered by a bodySHA256 query parameter that is part of the signed URL.
Which secret does Twilio use?
Your account's auth token. If you rotate the token, signatures change immediately.