Webhook Delivery Constraints
Twilio does not currently provide a configurable delivery window, a maximum retry interval setting, or a guaranteed delivery timeframe for status webhooks. The platform operates on an asynchronous push model where status updates are triggered by carrier reports; because these reports are subject to external carrier latency and internal queuing, the timing of the POST request to your endpoint cannot be strictly enforced or guaranteed by the developer.
Likely Behavior vs. Confirmed Facts
It is important to distinguish between the event occurrence and the webhook notification:
- Confirmed: Twilio uses an internal exponential back-off strategy for failed webhook deliveries. This logic is managed by the platform and is not exposed via API or the Console for modification.
- Confirmed: The
MessageStatus payload contains a timestamp. This represents when the event occurred in Twilio's system, not when the webhook was delivered to your server.
- Likely: Due to the reliance on third-party carrier networks, a "guaranteed delivery window" is architecturally improbable for SMS, as Twilio cannot control when a carrier reports a
delivered or undelivered state.
Best Practices for Real-Time Status Capture
Since you cannot force a stricter delivery deadline, use a hybrid approach to approximate real-time tracking and ensure data integrity:
- Implement a Polling Fallback: For time-critical messages, do not rely solely on the webhook. Use the Message Resource API to poll the status of a specific Message SID if a webhook has not arrived within your required business window.
- Handle Out-of-Order Delivery: Webhooks may arrive out of sequence (e.g.,
delivered arriving before sent). Always compare the status transition or the provided timestamp against your local database record before updating the message state.
- Idempotency Checks: Ensure your endpoint can handle duplicate notifications, as the retry mechanism may occasionally deliver the same status update more than once.
Verification Steps
To quantify the latency in your specific environment, you can implement a simple logging check:
// Example logic for latency tracking
const twilioTimestamp = request.body.MessageStatusTimestamp;
const arrivalTimestamp = new Date().toISOString();
const latency = calculateDiff(twilioTimestamp, arrivalTimestamp);
console.log(`Webhook Latency: ${latency}ms`);
Diagnostic Detail Needed: Are you experiencing specific timeouts (e.g., 504 Gateway Timeouts) on your endpoint, or are you seeing a significant gap between the MessageStatusTimestamp and the actual arrival time of the request?
twilio