Webhook documentation
SMS Delivery Report (DLR) Webhook Integration
An SMS DLR webhook is an HTTPS endpoint on your server that receives the delivery report for each SMS you send (delivered, failed, expired and so on), so your systems can update message status without polling.
Updated
What is an SMS DLR webhook?
DLR stands for delivery report: the status an operator returns for an SMS after it has been handed over for delivery. A DLR webhook forwards that status to a URL you host the moment it is available. Typical uses are confirming that an OTP reached the phone, triggering a fallback when a transactional alert fails, and measuring delivery for a promotional campaign.
Message submission and delivery lifecycle
- Submission. Your system sends the SMS through the API with the DLT-registered sender header, template ID and variables.
- Acceptance. The API validates the request and returns a message ID. Nothing has reached the handset yet.
- Hand-off. The message is passed to the operator route; interim statuses such as submitted or sent may be reported.
- Delivery attempt. The operator tries to deliver to the handset, retrying within the message validity period if the phone is unreachable.
- Delivery report. The operator returns a final result, which is sent to your callback URL as a DLR event carrying the same message ID.
Requests that do not match the registered header or template can be rejected before delivery. The DLT registration guide explains how headers and templates are registered.
Submitted, sent, delivered and failed statuses
| Status | Typical meaning | Final? |
|---|---|---|
| PENDING | Accepted by the API and waiting to be processed or submitted. | No |
| SUBMITTED | Handed to the onward messaging route or operator. | No |
| SENT | Sent from the platform; a handset delivery report has not yet arrived. | No |
| DELIVERED | The operator reported delivery to the handset. | Yes |
| FAILED | Delivery could not be completed, for example because of a network or platform error. | Yes |
| REJECTED | Refused before delivery, for example a template, header or scrubbing mismatch under DLT rules. | Yes |
| EXPIRED | Not delivered within the validity period, for example because the handset stayed unreachable. | Yes |
| UNDELIVERED | The operator reported the message as not delivered. | Yes |
Operator error codes
Failed, rejected and undelivered reports usually include an error code. Codes differ between operators and providers, so store the raw code exactly as received and map it to a small set of actions:
| Category | Typical causes | Suggested action |
|---|---|---|
| Invalid recipient | Number does not exist or is not a mobile number | Suppress the number and flag the record for correction |
| Temporarily unreachable | Handset switched off, out of coverage or memory full | Allow a later retry or another channel, within your consent rules |
| Preference or scrubbing block | DND preference or category mismatch | Check the message category and consent; do not retry unchanged |
| Content or registration mismatch | Header or template does not match the DLT registration | Fix the template or header registration before sending again |
| Platform or network error | Temporary error on the route | Retry with backoff and alert if the rate rises |
Message ID mapping
Store the provider message ID in the same row as your own reference before relying on any webhook. A minimal message table holds:
- your internal reference (order number, user ID, OTP request ID or campaign ID)
- the provider message ID returned at submission
- the current status and the timestamp of that status
- the last error code, if any
Long messages are split into several parts. Depending on the provider, a multi-part SMS may return one message ID or one per part, so confirm how your account reports them before aggregating delivery counts.
Delivery timestamps
A DLR commonly carries the time the message was submitted and the time the status was recorded. Store both in UTC. The status time orders events correctly when they arrive late; the difference between the two measures delivery latency, which is useful for OTP flows where a slow message is effectively a failed one.
Illustrative SMS delivery event
{
"event_id": "evt_example_001",
"event_type": "message.delivered",
"message_id": "msg_example_123",
"channel": "sms",
"status": "DELIVERED",
"timestamp": "2026-11-08T10:30:00Z"
}For SMS, message_id is the value returned when you submitted the message, and event_id is unique to this delivery report, so a retried DLR repeats the same event_id. status holds the operator-derived result, channel is sms, and timestamp is when the report was recorded rather than when it reached your server.
DLR callbacks vs polling
With callbacks, each DLR is pushed to you once it exists. With polling, your system asks for the status of outstanding messages on a schedule. For OTPs and alerts, callbacks give near real-time status with far fewer requests. Polling, where the API offers it, remains useful as a nightly reconciliation for messages that never received a final report, for example after an outage on your endpoint.
SMPP delivery receipts vs HTTP webhook callbacks
This guide covers delivery reports pushed to an HTTPS callback URL. If your platform connects over SMPP instead, receipts do not arrive as webhooks: the SMSC sends each receipt as a deliver_sm PDU on your transceiver (TRX) or receiver (RX) session, and your client must acknowledge it with deliver_sm_resp. Correlation works the same way, using the message ID returned in submit_sm_resp.
See receiving DLRs through deliver_sm in the SMPP v3.4 integration guide, and the TXTPro SMPP account page for supported bind types.
Retry and duplicate delivery handling
- Acknowledge each DLR with a 2xx response as soon as it is verified and queued; slow responses are the most common cause of duplicates.
- Insert the event ID into a table with a unique constraint before processing, and skip events that already exist.
- Never let an interim status (submitted, sent) overwrite a final one (delivered, failed, rejected, expired, undelivered).
- Whether and how often the sender retries depends on the configuration for your account and is confirmed during onboarding.
The webhook security guide covers authentication, replay protection and dead-letter queues in more depth.
Updating your CRM from delivery reports
Most teams do not write DLRs straight into the CRM. A small service receives and stores the reports, then updates the CRM in batches or through its API: marking a contact’s mobile as invalid after repeated invalid-recipient errors, recording that a payment reminder was delivered, or creating a task when a critical alert fails. Keeping the raw events in your own store also gives you an audit trail.
Working receivers are shown in the Node.js webhook guide and the Python webhook guide.
Troubleshooting SMS DLR webhooks
| Symptom | What to check |
|---|---|
| No DLRs arrive | Callback URL configuration, public DNS, TLS certificate, firewall and allowlisting |
| Every request fails verification | Verification must use the raw body and the secret for the correct environment |
| Many duplicate DLRs | Endpoint response time; acknowledge before slow processing |
| Status stuck at SENT | Some routes or handsets return late or no final report; reconcile after your validity window |
| DLRs for unknown message IDs | Submission responses not being saved, or multi-part messages reporting per part |
Event names, status values, field names, authentication and retry behaviour depend on the provider API specification for your account. TXTPro confirms the exact format, callback registration and any allowlisting steps during onboarding.
Frequently asked questions
What is an SMS DLR webhook?
An SMS DLR webhook is an HTTPS endpoint on your server that receives SMS delivery reports, such as delivered, failed or expired, automatically as the operator reports them.
How quickly does an SMS delivery report arrive?
Usually shortly after delivery, but timing depends on the operator, the handset and network conditions. Some messages receive a late or no final report, so plan a reconciliation step.
Why did a delivered report arrive before the sent status?
Events travel independently and can arrive out of order. Use the status timestamp and treat final statuses as terminal so an older interim event cannot overwrite them.
Are the SMS status names on this page TXTPro’s exact values?
No. They are common, typical values. The exact status values and error codes for your account depend on the provider integration and are confirmed during onboarding.
