Test and debug Twilio webhooks

Pointing a Twilio callback at a test URL

Create a URL above, then set it as a callback. For SMS status, the quickest route is the API call itself:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$ACCOUNT_SID/Messages.json" \
  --data-urlencode "To=+15558675310" \
  --data-urlencode "From=$TWILIO_NUMBER" \
  --data-urlencode "Body=hello" \
  --data-urlencode "StatusCallback=https://trywebhook.com/w/your-bin-id" \
  -u "$ACCOUNT_SID:$AUTH_TOKEN"

You will get several deliveries in sequence — queued, then sent, then delivered — each a separate POST. Watch them arrive in order in the list.

For incoming messages, set the URL under Phone Numbers → Manage → Active numbers → your number → A message comes in. Twilio will then expect TwiML in the response, which a capture bin does not return; the message still arrives here, and Twilio logs an error about the response. That is expected and harmless while you are inspecting.

Form-encoded, and what that means

The body of the sample above is one line:

SmsSid=SM00000000000000000000000000000000&SmsStatus=delivered&MessageStatus=delivered&To=%2B15558675310&...

No JSON anywhere. Phone numbers are percent-encoded, so +15558675310 arrives as %2B15558675310 and a handler that treats it as a literal string will store a space where the plus should be.

Reading it correctly:

const form = await request.formData();
const status = form.get('MessageStatus');
const sid = form.get('MessageSid');

MessageSid is your join key back to the send. SmsSid is the same value under an older name, and both are present for compatibility.

Error codes carry the real information

On a failed or undelivered status you also get ErrorCode. It is the difference between a problem you can fix and one you cannot:

• 30003 — unreachable destination handset. Retry later, maybe.
• 30005 — unknown destination. The number is wrong; stop trying.
• 30007 — carrier filtering. Your content or sender reputation triggered a block.
• 30008 — unknown error from the carrier. Genuinely opaque.

Verifying X-Twilio-Signature

This is the most unusual scheme of any provider on this site, because the signature covers more than the body. Twilio builds the signed string by taking the full URL it called, then appending each POST parameter’s name and value, sorted alphabetically by name, with no separators:

https://trywebhook.com/w/your-bin-idAccountSidAC00...ApiVersion2010-04-01From+15551234567MessageSid...

Then HMAC-SHA1 with your auth token, base64-encoded. Two consequences worth internalising:

The URL must match exactly. Scheme, host, port, path, and query string. Behind a load balancer that terminates TLS, your framework will reconstruct http:// and the digest will differ. Every official Twilio helper library takes the URL as an explicit argument precisely so you can pass the public one.

Parameter order is defined by sorting, not by arrival. So the raw body order does not matter for verification — but the values must be the decoded ones, not the percent-encoded ones.

In the Signature tab above, choose Twilio and paste your auth token. The URL is taken from the request as captured, including the path and query, which is usually the piece that reveals the mismatch.

Not retried, so log first

Status callbacks fire once. There is no delivery log in the Console you can replay from, and no retry to save you. Whatever your handler does, it should record the raw form body before it does anything that can throw — a parse error on one unexpected field should not lose the delivery notification entirely.