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

1. You send a message via SMSTAKE REST API and receive a message_id in the response
2. SMSTAKE routes the message to Jio, Airtel, Vi, BSNL, or the relevant WhatsApp/RCS channel
3. The operator or channel returns a delivery status (delivered, failed, expired, etc.)
4. SMSTAKE POSTs a JSON payload to your registered webhook URL
5. 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)

New to delivery reports? SMS delivery reports explained covers what each status means in plain language, and why delivered doesn't mean read.

Sample Webhook Payload

An illustrative delivery report looks like this (the exact field names and headers are in the API documentation shared during onboarding):

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

1. Open the delivery report (webhook) settings in your SMSTAKE account, or ask our team to configure your endpoint
2. Add your HTTPS endpoint URL (must be publicly reachable)
3. Select events: DLR / Delivery Reports (and optionally read receipts for WhatsApp)
4. Copy the webhook signing secret for payload verification
5. Send a test message from the sandbox - confirm your server logs the DLR
6. 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

Retry behaviour and webhook logs depend on your account setup - our team can confirm the details during onboarding.

Get Started

DLR webhooks are included on all SMSTAKE API plans. Start with the sandbox, register your endpoint, and go live once onboarding is complete.

API overview | Bulk SMS | OTP SMS guide | Get Webhook API