Carrier DLR webhooks arrive asynchronously and frequently out of order; handlers must be idempotent and synchronize message state machines cleanly.
When you dispatch an SMS, an HTTP 200 response from Twilio or Telnyx merely confirms that the aggregator accepted your API request. Actual handset arrival is reported minutes later via asynchronous Delivery Receipts (DLR). Designing a robust ingestion pipeline for these webhooks is critical for deliverability telemetry.
1 DLR Status State Machine
Standard telecom DLR status codes follow a progression:
- queued: Stored in aggregator buffer.
- sending: Transmitted to upstream carrier over SMPP.
- sent: Dispatched to the destination carrier's SMSC.
- delivered: Mobile handset confirmed reception.
- undelivered / failed: Delivery failed due to disconnected number, carrier spam block, or handset offline.
2 Out-of-Order Webhook Concurrency
Because carrier networks operate distributed queuing pipelines, a 'delivered' DLR webhook can arrive before the initial 'sent' status. Handlers must use monotonic timestamp checks or state machine guards so late-arriving earlier statuses never overwrite a terminal 'delivered' state in the database.
Frequently Asked Questions • OTP & 2FA Engineering
No. 'Sent' only confirms delivery to the recipient's mobile network operator. Handset delivery is only guaranteed when the terminal 'delivered' status receipt arrives.
On healthy Tier-1 carrier routes, 95-98% of messages receive terminal delivery receipts within 30 seconds. Some international carriers do not return terminal DLRs.