Twilio — request signature validation failed for webhook

Twilio webhook handler rejects the request because the X-Twilio-Signature header does not match the expected HMAC computed from the auth token and URL.

intermediatedebuggingtwiliowebhook

Symptoms

Error: Invalid Twilio signature
The webhook works with ngrok but not in production
Signature validation passes locally but fails behind a proxy

Possible causes

The URL used to validate does not match the URL Twilio called (proxy or trailing slash)
The auth token in the app does not match the Twilio account token
The request body is parsed before signature validation, altering the raw body

Diagnosis steps

Compare the validation URL with the Twilio webhook URL

echo $WEBHOOK_URL

Interpretation

The URL must exactly match what Twilio sends, including protocol and path.

Verify the auth token

twilio api:core:accounts:fetch

Interpretation

The auth token used for HMAC must match the account token.

Root cause

The HMAC signature computed by Twilio uses the auth token and the full URL; if the validation URL or token differs, the signatures do not match and the request is rejected.

Fix

Use the exact URL Twilio calls for validation, ensure the auth token matches, and validate the signature before parsing the body to preserve the raw content.

Verify the fix

Send a test webhook from the Twilio console and confirm the handler accepts it; verify a forged request is rejected.

Symptom walkthrough

Twilio webhook handler rejects the request because the X-Twilio-Signature header does not match the expected HMAC computed from the auth token and URL. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The HMAC signature computed by Twilio uses the auth token and the full URL; if the validation URL or token differs, the signatures do not match and the request is rejected.

Fix

Use the exact URL Twilio calls for validation, ensure the auth token matches, and validate the signature before parsing the body to preserve the raw content. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Send a test webhook from the Twilio console and confirm the handler accepts it; verify a forged request is rejected. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

echo $WEBHOOK_URL
twilio api:core:accounts:fetch