Validate Twilio webhook signatures with the SDK, not custom code

TL;DR

Use the helper library validator: in node it is twilio.validateRequest, other SDKs ship a RequestValidator class. Check it before you act on the webhook, or anyone can fake delivery receipts and inbound messages. Pass your auth token, the exact full URL Twilio called, the POST params, and the signature. Validate against whatever params arrive; never hardcode the expected set or your validator breaks on a quiet Twilio change.

When to use

You are seeing this: Every request Twilio sends your app carries an X-Twilio-Signature header. Use this skill when you run into "Validate Twilio webhook signatures with the SDK, not custom code".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Every request Twilio sends your app carries an X-Twilio-Signature header. Check it before you act on the webhook, or anyone can fake delivery receipts and inbound messages.

Procedure

1. Read the X-Twilio-Signature header on every inbound webhook request.
2. Use the helper library validator: in node it is twilio.validateRequest, other SDKs ship a RequestValidator class. Pass your auth token, the exact full URL Twilio called, the POST params, and the signature.
3. The URL must match exactly what Twilio requested, scheme and host included. Behind a proxy or load balancer this is the classic failure: your app sees http on an internal port while Twilio called https on your public host, and validation fails. Reconstruct the public URL (X-Forwarded-Proto and friends) before validating.
4. Webhooks arrive form-encoded, not JSON. Parse the body as form params first, then validate.
5. Twilio adds webhook parameters over time without notice. Validate against whatever params arrive; never hardcode the expected set or your validator breaks on a quiet Twilio change.
6. Reject invalid signatures with a 403 and log the attempt. Never process the message first and validate later.

Gotchas

• Do not implement the HMAC yourself. The SDK handles param sorting and encoding edge cases you will get wrong.
• If validation suddenly fails after a deploy, check the URL first: scheme, host, port, and any path prefix your proxy adds.
• The auth token used for validation is the same one from your console. Keep it out of client-side code and agent-visible logs.

Verified against Twilio's webhook security docs (2026-09-26). Twilio signs all webhook requests with an X-Twilio-Signature header, computed as HMAC-SHA1 over the full request URL plus sorted POST params using your auth token as the key. The docs explicitly recommend using the SDK validator instead of a custom implementation, and note webhook params evolve over time. Source: https://www.twilio.com/docs/usage/webhooks/webhooks-security