DLR Webhook Guide - Real-Time Delivery Reports

A DLR (Delivery Report) tells you whether a message was delivered, failed, or rejected by the operator. With a DLR webhook, SMSTAKE pushes that status to your server in real time - so you never have to poll the API or guess if an OTP, alert, or campaign message actually reached the customer.

What Is a DLR Webhook?

When you send SMS, RCS, WhatsApp, or Voice messages through SMSTAKE, each message gets a unique message ID. As the message moves through the network, operators and channels return delivery updates. Instead of asking SMSTAKE repeatedly for status, you register a webhook URL - and we POST the DLR to your endpoint the moment it changes.

Push, not poll - instant updates without extra API calls
Event-driven - your app reacts only when status changes
Multi-channel - one webhook flow for SMS, RCS, WhatsApp & Voice
Audit-ready - full trail for compliance, billing & support

Why Your Business Needs DLR Webhooks

OTP & login flows - confirm delivery before showing "OTP sent" or triggering Voice fallback
Transactional alerts - mark orders, payments & appointments as notified only after delivered
Campaign analytics - track delivered vs failed counts in your own dashboard
Billing reconciliation - match sent volume with operator-confirmed delivery
Support & debugging - trace a customer's message with message ID + error code
DLT compliance - prove transactional messages reached the handset on Indian routes

How DLR Webhooks Work

You send a message via SMSTAKE REST API and receive a message_id in the response
SMSTAKE routes the message to Jio, Airtel, Vi, BSNL, or the relevant WhatsApp/RCS channel
The operator or channel returns a delivery status (delivered, failed, expired, etc.)
SMSTAKE POSTs a JSON payload to your registered webhook URL
Your server returns HTTP 200 - we log success; non-2xx responses trigger automatic retries

Common DLR Status Values

queued / submitted - accepted by SMSTAKE, pending operator dispatch
sent - handed off to the operator or channel
delivered - confirmed on the recipient's device
failed - permanent failure (invalid number, DND, template mismatch)
rejected - blocked by DLT, operator, or channel policy
expired - not delivered within the validity window
undelivered - handset unreachable or switched off (may retry on some routes)

Sample Webhook Payload

Your endpoint receives a POST request like this:

POST https://yourapp.com/webhooks/smstake/dlr
Content-Type: application/json
X-SMSTAKE-Signature: sha256=...

{
 "event": "message.dlr",
 "message_id": "msg_8f3k2j9x1m",
 "channel": "sms",
 "to": "+919876543210",
 "from": "SMSTKE",
 "status": "delivered",
 "status_code": "DELIVRD",
 "operator": "JIO",
 "submitted_at": "2026-06-30T10:15:02+05:30",
 "delivered_at": "2026-06-30T10:15:04+05:30",
 "dlt_template_id": "1207165123456789012",
 "client_ref": "order_ORD2847",
 "error_code": null,
 "error_message": null
}

Use client_ref to link the DLR back to your order, user session, or campaign row in your database.

Setting Up DLR Webhooks on SMSTAKE

Log in to the SMSTAKE dashboard → Developers → Webhooks
Add your HTTPS endpoint URL (must be publicly reachable)
Select events: DLR / Delivery Reports (and optionally read receipts for WhatsApp)
Copy the webhook signing secret for payload verification
Send a test message from the sandbox - confirm your server logs the DLR
Go live - all production traffic will push DLRs to your URL

Security Best Practices

HTTPS only - never expose a plain HTTP webhook in production
Verify signatures - validate X-SMSTAKE-Signature on every request
Idempotent processing - the same DLR may be retried; deduplicate by message_id + status
Respond fast - return 200 OK within 5 seconds; queue heavy work asynchronously
IP allowlisting - optional extra layer for enterprise deployments
Never log full OTP content - store message IDs and status, not sensitive message body

DLR Webhooks by Channel

SMS - operator-level DLR with TRAI/DLT error codes for rejected templates
RCS - delivered, read & failed events with rich-message context
WhatsApp - sent, delivered, read & failed statuses per Meta guidelines
Voice (OBD/IVR) - answered, busy, no-answer & call-duration reports

Troubleshooting Failed Webhooks

404 / 500 errors - check your route exists and returns 200 for POST
Timeouts - offload database writes to a background job
Missing DLRs - confirm webhook is enabled for the correct environment (sandbox vs live)
Duplicate events - implement idempotency keys; retries are normal
SSL issues - ensure a valid certificate on your domain

SMSTAKE retries failed webhook deliveries with exponential backoff for up to 72 hours. View delivery logs in the dashboard under Reports → Webhook Logs.

Get Started

DLR webhooks are included on all SMSTAKE API plans. Start with the sandbox, register your endpoint, and go live in minutes.

API integration | OTP SMS guide | Get Webhook API