Twilio webhooks in production: duplicates, ordering, retries and timeouts

Published · Updated

This guide covers the problems Twilio webhooks cause in production and how to handle each one. What Twilio sends and how it's signed is on the Twilio webhooks overview, the event types are on Twilio webhook events, and signature verification code is on Verify Twilio webhooks.

Twilio has two systems that send you webhooks, and the answers often differ between them. Classic webhooks come from Messaging, Voice and other products, which call a URL you set on a number or resource with form-encoded parameters. Event Streams sends JSON CloudEvents to a sink you subscribe to event types. Twilio's own advice is webhooks when you need to respond with TwiML, and Event Streams when you only need information.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsAnswer within 15 seconds, or 5 on Conversations (classic) and Event Streams; queue the restAccepts status callbacks and Event Streams deliveries at once, then queues them for your service
DuplicatesKey on MessageSid or CallSid plus status, or on the CloudEvent idDrops repeats before they reach your handler
OrderingOnly move status forward; sort Event Streams events by timestampLogs every event and attempt, so you can see arrival order when debugging
RetriesSet rc and rp, add fallback URLs, and reconcile from the REST APIKeeps failed deliveries and retries them on your schedule
Choosing eventsPick the right system, and subscribe only to what you processFilters and routes events by any property
TestingUse a tunnel; test a bad signature and the failure pathsForwarding and replay with the CLI
TwiML, form bodies and other limitsParse forms, answer TwiML yourself, and plan for callback volumeOne stable URL, transformations and a delivery rate you set

Twilio webhook timeouts and slow handlers

Answer within Twilio's limit and do slow work in a background job. The limit depends on the product.

Why it happens: Twilio waits 5 seconds to connect and 15 seconds for a response by default, and those 15 seconds are also the default total, retries included. The limits differ by product:

  • Voice. Twilio imposes a hard 15-second limit on all call-related requests, because a caller is waiting. No override or setting raises it.
  • Conversations (classic). The maximum is 5 seconds. If a pre-action webhook gets no response in time, Twilio publishes the change unmodified, so a check that runs too long blocks nothing.
  • Event Streams. The maximum for a webhook sink is 5 seconds.
  • Other webhooks. A Webhook Setting allows up to 15 seconds each for connecting and reading, and a total of up to 60 seconds. URL overrides stop at 10 seconds to connect and 15 to read or in total.

Fix it in your handler:

  1. Validate the signature, then answer. A status callback needs an HTTP 200 and nothing else.
  2. Push the work onto a queue and process it in a worker. See why to process webhooks asynchronously.
  3. For a webhook that needs TwiML, build the response from data you can read quickly. If the slow part can wait, return the TwiML and queue it.
  4. Keep cold starts short on serverless, since connecting and reading both count against the total.

With Event Gateway: Point status callbacks and Event Streams sinks at Hookdeck, which accepts each delivery within Twilio's limit and delivers it to your service with its own timeouts and retries. Webhooks that need your TwiML stay on your own endpoint: see TwiML, form bodies and other limits.

Duplicate Twilio webhook events

Twilio sends each webhook at least once, so make handlers idempotent and deduplicate by product.

Why it happens: Retries repeat a delivery, and a handler that finishes its work but responds too late sees the same request again. Event Streams can also resend during incident remediation and internal errors, not only after your endpoint fails. Twilio's Event Streams page calls webhooks exactly once while its security guide says at least once, so plan for repeats.

Fix it in your handler:

  1. For a status callback, build the key from the SID and the status, such as MessageSid and MessageStatus, or CallSid and CallStatus. A message legitimately sends several callbacks with one SID.
  2. For Event Streams, key on the CloudEvent id: duplicates have the same id. Return a 200 when you discard one, because anything else can cause another retry.
  3. Don't treat I-Twilio-Idempotency-Token as an event key. Twilio says it distinguishes retry attempts, and its docs don't say whether a retry repeats the value.
  4. Make every handler idempotent.
async function processStatusCallback(params) {
  const key = `${params.MessageSid}:${params.MessageStatus}`;

  // SET NX returns null when the key already exists
  const first = await redis.set(`processed:${key}`, '1', 'EX', 86400, 'NX');
  if (!first) return;

  await updateMessageStatus(params.MessageSid, params.MessageStatus);
}

With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

Out-of-order Twilio webhook events

Twilio doesn't guarantee order on status callbacks or Event Streams, so only let state move forward.

Why it happens: Status transitions can happen in quick succession and each is its own HTTP request, so there is no guarantee that status callback requests arrive in the order they were sent. Event Streams says the same of its deliveries: it might deliver events out of order, and retries can run for hours. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.

Fix it in your handler:

  1. Rank the statuses you handle and ignore any callback that would move a message backwards.
  2. For Event Streams, use each event's timestamp to sort events, as Twilio suggests.
  3. When only the current state matters, treat the callback as a signal and fetch the Message or Call resource from the REST API.
const RANK = { queued: 1, sent: 2, failed: 3, undelivered: 3, delivered: 3, read: 4 };

async function applyStatus({ MessageSid, MessageStatus }) {
  const current = await db.getMessageStatus(MessageSid);
  if (!current || RANK[MessageStatus] > RANK[current]) {
    await db.updateMessageStatus(MessageSid, MessageStatus);
  }
}

With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.

Twilio webhook retries and lost callbacks

By default Twilio retries a classic webhook once, and only after a connection failure. Set a retry policy, and reconcile from the REST API for anything you can't afford to lose.

Why it happens: The default retry count is 1 and the default retry policy is ct, a TCP connect or TLS handshake failure. A 500 from your server or a read timeout doesn't trigger it. The two systems then differ:

Twilio's docs describe no way to resend a classic webhook. Errors go to the Debugger, and that is the record of what failed.

Fix it in your handler:

  1. Set a retry policy on the webhooks that matter, and make sure your handler is safe to run twice.
  2. Set a fallback URL on inbound numbers, such as SmsFallbackUrl, so an error at your main URL still reaches something.
  3. Reconcile. Twilio's delivery logging guide says to poll a message with no delivered or undelivered status after 12 hours, and to reconcile statuses at least once a day.
  4. For Event Streams, return 429 to slow delivery while keeping the event, and 400 only when you want it discarded.
  5. Watch errors with the Debugger webhook or the Monitor REST API, since nothing else tells you a callback was missed.

With Event Gateway: Hookdeck acknowledges deliveries while your service is down and retries to your service on your schedule, well past Twilio's defaults. You can inspect failed attempts and replay them once the endpoint is fixed.

Choosing which Twilio events to listen to

Use classic webhooks when your response controls the message or call, and Event Streams when you only need to know what happened. Then subscribe only to what you process.

Why it matters: The two systems identify events differently, so the choice sets your routing:

  • Classic webhooks have no event type field. The URL says what the request is. MessageStatus, CallStatus and RecordingStatus report state on their own callbacks. Separate URLs for each kind of webhook keep your routing simple.
  • Conversations (classic) names the action in EventType. Most actions have a pre-action webhook, which can change or reject them, and a post-action one. Out of the box only SDK-driven and SMS-based actions trigger webhooks. REST API actions need an X-Twilio-Webhook-Enabled=true header on the request.
  • Event Streams names the event in type. You subscribe per event type and schema version. The body is a JSON array that currently holds one event, and Twilio says to iterate over it anyway.

Some event names are also on their way out. Twilio marks types as deprecated, restricted or discontinued, and a discontinued type may stop arriving even on an existing subscription. On the voice page, com.twilio.voice.webhook.status-callback.call.* is deprecated and com.twilio.voice.status-callback.call.* sits beside it.

Fix it in your handler:

  1. Give each kind of classic webhook its own URL, and check which one you're on before you read its parameters.
  2. For voice, name the statuses you want with StatusCallbackEvent. By default Twilio only calls when the call completes.
  3. For Messaging, expect a callback per status change. Twilio's docs describe no way to filter them, so filter in your handler, or subscribe to Event Streams types instead.
  4. Voice events in Event Streams only arrive when your API request or TwiML also asks for them, so add a status callback URL and the events you want there.
  5. Create a subscription per subaccount, as one subscription can't cover them all.

With Event Gateway: Hookdeck filters and routes events by type or any other property, so one URL can feed several services.

Testing and debugging Twilio webhooks locally

Use a tunnel, and test a bad signature and your failure paths as well as real messages.

Why it happens: Twilio needs an internet-reachable URL and won't connect to HTTPS with a self-signed certificate. A signature also covers the URL, so a tunnel URL that differs from what your code rebuilds fails verification even when everything else is right.

Fix it in your testing:

  1. Run your handler behind ngrok or another tunnel, and point a number at it with twilio phone-numbers:update.
  2. Send a request with a bad signature and check that it's rejected. A mock request from curl or Postman needs a valid signature to get past validation.
  3. Send real traffic. Twilio suggests calling your number and sending it messages, and using the requests the Debugger shows as test cases.
  4. Test an Event Streams sink with the Sink Test resource, which publishes a test event, and test a Webhook Setting with the Tests endpoint. There, a 200 means the test ran, so read result.outcome.
  5. Read what was sent. For voice, the Request Inspector shows the exact request and your response, and those logs are kept for 30 days. The Debugger searches the last 30 days too.
  6. Try the failure paths: a handler that returns a 500, one that takes longer than the limit, and callbacks out of order.

With Event Gateway: The Hookdeck CLI forwards events to your machine through one stable URL and replays past ones, so you can test a fix without sending another message.

TwiML, form bodies and other limits

TwiML responses. An inbound message or call expects TwiML in your response, so the request and your answer are one exchange. Keep these webhooks on an endpoint that can answer them. If you only want to record inbound messages, an empty <Response> element is a valid reply.

Form-encoded bodies. Messaging, Voice and Conversations (classic) use application/x-www-form-urlencoded, so a JSON-only body parser leaves you without the parameters. Use express.urlencoded() or your framework's equivalent. Event Streams is JSON, so an app handling both needs both parsers. A webhook set to GET carries the same values in the query string.

Changing parameters. Twilio adds parameters without advance notice. Accept unknown ones, and don't list the parameters you expect in your signature check.

One URL per number. Each number has its own webhook settings, so a change of endpoint means updating every one. Messaging Services group numbers under one status callback, and you can update numbers in bulk through the REST API. Webhook Rules match the destination URL, so they change delivery settings rather than where a webhook goes.

Callback volume. Each message can send a callback per status. Twilio's own example is 10 million messages producing 20 million callbacks, and it calls that an operational risk. Size your endpoint for the status traffic as well as the sends.

Authenticating Twilio. Beyond the signature, Twilio can send OAuth 2.0, Basic or Digest credentials through the Webhooks configuration API. Event Streams sinks support Basic only, in the URL.

IP allowlists. Twilio has no fixed range for classic webhooks, and suggests a proxy in a DMZ. Event Streams webhooks come from published CIDR blocks. Both can change, so keep the signature check.

With Event Gateway: Use one stable Hookdeck URL across your status callbacks, and route and filter there instead of changing numbers one at a time. A transformation can reshape form parameters into the JSON your service expects, and you set a maximum delivery rate so a burst of callbacks reaches your service at a pace it can take. For inbound messages you only record, a custom response can return the empty TwiML.

Keep a failed callback from being lost after Twilio's one retry.

Point status callbacks and Event Streams sinks at Hookdeck Event Gateway. It accepts each delivery, queues it and retries to your service on your schedule, with a log of every attempt.

Not affiliated with Twilio. Facts are compiled from public sources and linked inline.