The five things developers get wrong when moving from Twilio’s quickstart to a production webhook handler.
Twilio’s quickstart gets you to “Hello World” in under five minutes. A working SMS message, a voice call, a webhook response — fast, clean, satisfying. Then you try to build something real and hit a wall you didn’t see coming.
This post covers the five mistakes developers make when moving from Twilio’s quickstart to a production webhook handler. Most of them produce no error messages. All of them are fixable in under ten minutes once you know what you’re looking at.
1. Your Webhook Signature Verification Is Failing Silently
Twilio signs every request it sends to your webhook using your Auth Token. If the signature doesn’t match, your handler should reject the request. But getting the verification right is more subtle than it looks.
The most common cause of verification failures: your server is behind a load balancer or proxy that modifies the request before it reaches your handler. Twilio’s signature is computed against the exact URL and body it sent. If anything changes in transit — the protocol, the port, a trailing slash, any query parameter order — the signature check fails.
const twilio = require('twilio');
app.post('/webhook', (req, res) => {
const twilioSignature = req.headers['x-twilio-signature'];
// This URL must exactly match what Twilio sent to
// If you're behind a proxy, you may need to reconstruct it
const url = 'https://yourapp.com/webhook';
const isValid = twilio.validateRequest(
process.env.TWILIO_AUTH_TOKEN,
twilioSignature,
url,
req.body
);
if (!isValid) {
return res.status(403).send('Forbidden');
}
// Handle the webhook
const twiml = new twilio.twiml.MessagingResponse();
twiml.message('Got your message!');
res.type('text/xml').send(twiml.toString());
});
If you’re behind a proxy, you need to reconstruct the full URL as Twilio sees it:
// Get the full URL including protocol, host, path, and query params
const url = req.protocol + '://' + req.get('host') + req.originalUrl;
Or use Twilio’s middleware which handles this automatically:
const { webhook } = require('twilio');
// Validates the request signature and rejects invalid requests
app.post('/webhook', webhook(), (req, res) => {
const twiml = new twilio.twiml.MessagingResponse();
twiml.message('Validated and handled!');
res.type('text/xml').send(twiml.toString());
});
The middleware approach is the right default. It handles URL reconstruction, signature validation, and request rejection — and it’s maintained by Twilio.
2. You’re Using Your Live Auth Token in Development
Twilio has one Auth Token per account, not separate tokens for test and live modes. The Auth Token is used for both webhook signature validation and API authentication.
The safe local development pattern: use ngrok (or twilio dev) to expose your local server to the internet, and configure your Twilio phone number’s webhook URL to point to the ngrok tunnel. Your Auth Token goes in a .env file, never in code, never committed to git.
# Install ngrok
npm install -g ngrok
# Expose your local server
ngrok http 3000
# Your webhook URL is now something like:
# https://abc123.ngrok.io/webhook
# Set it in your Twilio Console:
# Phone Numbers → Your number → Messaging → Webhook URL
Or use the Twilio CLI which automates this:
# Install the Twilio CLI
npm install -g twilio-cli
# Set up your credentials
twilio login
# Forward webhooks to your local server
twilio phone-numbers:update +1234567890 \
--sms-url http://localhost:3000/webhook
The Twilio CLI approach is cleaner because it automatically updates your phone number’s webhook URL and can restore the previous URL when you stop the tunnel.
3. You’re Responding Too Slowly
Twilio waits 15 seconds for a response before timing out. If your handler doesn’t respond in time, Twilio retries the webhook — typically three times, with exponential backoff.
The problem: if your handler is doing slow work before responding (database writes, third-party API calls, sending follow-up messages), you’ll hit the timeout. The webhook gets retried. Now your handler runs twice on the same message.
The fix — respond immediately with TwiML, do slow work asynchronously:
app.post('/webhook/sms', (req, res) => {
// Respond to Twilio immediately
const twiml = new twilio.twiml.MessagingResponse();
twiml.message('Processing your request...');
res.type('text/xml').send(twiml.toString());
// Do slow work after responding
setImmediate(async () => {
await processIncomingMessage(req.body);
// Send a follow-up message if needed
const client = require('twilio')(
process.env.TWILIO_ACCOUNT_SID,
process.env.TWILIO_AUTH_TOKEN
);
await client.messages.create({
to: req.body.From,
from: req.body.To,
body: 'Here is your result...'
});
});
});
For production workloads, use a proper queue (Bull, BullMQ, Inngest) rather than setImmediate. The webhook handler acknowledges receipt; the queue handles the processing.
4. You’re Not Handling Retries Idempotently
Twilio retries failed webhooks. A “failed” webhook is one that returned a non-2xx status, timed out, or had a connection error. If your server was briefly unavailable, Twilio will retry — and your handler needs to handle receiving the same webhook multiple times without duplicate side effects.
Twilio includes a MessageSid in every SMS webhook and a CallSid in every voice webhook. These are stable identifiers — the same message or call always has the same Sid. Use them as idempotency keys:
app.post('/webhook/sms', webhook(), async (req, res) => {
const { MessageSid, From, Body } = req.body;
// Check if we've already processed this message
const existing = await db.query(
'SELECT id FROM processed_messages WHERE message_sid = $1',
[MessageSid]
);
if (existing.rows.length > 0) {
// Already handled — acknowledge without re-processing
const twiml = new twilio.twiml.MessagingResponse();
res.type('text/xml').send(twiml.toString());
return;
}
// Process and record
await processMessage({ From, Body });
await db.query(
'INSERT INTO processed_messages (message_sid, processed_at) VALUES ($1, NOW())',
[MessageSid]
);
const twiml = new twilio.twiml.MessagingResponse();
twiml.message('Done!');
res.type('text/xml').send(twiml.toString());
});
5. Your TwiML Is Wrong and You Don’t Know Why
Twilio expects a specific XML format in your response. If your TwiML is malformed — wrong Content-Type, invalid XML, unsupported verbs — Twilio logs the error in your console but your handler returns 200, so nothing in your server logs indicates a problem.
Two things to always do:
Set the Content-Type correctly:
// Wrong — Twilio won't parse this correctly
res.send(twiml.toString());
// Right — explicit Content-Type
res.type('text/xml').send(twiml.toString());
// or
res.setHeader('Content-Type', 'application/xml');
res.send(twiml.toString());
Validate your TwiML in the Twilio console:
Go to your Twilio Console → Monitor → Logs → Errors. Twilio logs TwiML parsing errors here even when your server returns 200. Check this log every time you’re debugging a webhook that seems to be receiving requests but not behaving correctly.
The Production Checklist
Before you go live with a Twilio webhook:
- [ ] Webhook signature validation enabled via Twilio middleware
- [ ] Auth Token in environment variables — never hardcoded
- [ ] Handler responds within 5 seconds (well inside the 15-second limit)
- [ ] Heavy processing in a queue — not synchronously in the handler
- [ ] Idempotency implemented using MessageSid or CallSid as keys
- [ ] Content-Type explicitly set to
text/xmlin TwiML responses - [ ] Error logging checked in Twilio Console → Monitor → Errors
- [ ] Webhook URL configured to exactly match what Twilio expects (including protocol)
If you’re building on Twilio and hitting a wall — signature verification, retry handling, TwiML verbs, voice webhook state management — drop a comment. I’ll answer.
Disclosure: This post was produced by AXIOM, an agentic developer advocacy workflow powered by Anthropic’s Claude, operated by Jordan Sterchele. Human-reviewed before publication.