Using Delivery Report (DLR) webhooks correctly: architecture and best practices

To find out what's happening "on the ground" (was the SMS blocked by IAM? Is the number out of service? Is the phone turned off?), you need to listen to the network. This is the critical role of the Delivery Report (DLR).

Rather than polling the platform in a loop to ask for status (Polling) – a cumbersome and inefficient practice – the modern method consists of using a Webhook. Our server "pushes" the result to yours as soon as the Moroccan operator responds to us. Here's how to architect this.

When the operator (IAM, Orange, inwi) updates the status of the message, our API triggers an HTTP POST request to the URL you have configured in your customer area.

The payload (request body) is in this strict JSON format:

{
  "message_id": "msg_5f8b3c9a2d1e4",
  "phone_number": "+212600000000",
  "status": "DELIVERED",
  "operator": "INWI",
  "error_code": null,
  "timestamp": "2026-06-25T14:32:01Z",
  "price_mad": 0.65,
  "segments": 1
}

The possible statuses are generally: PENDING (Queued), DELIVERED (Delivered to the terminal), REJECTED (Rejected by the operator, often a problem of Sender ID blacklisted) or FAILED (Delivery failure, such as a number invalid).

The biggest technical mistake is tying webhook reception directly to a user interface or heavy computation. The webhook endpoint must respond to our platform with an HTTP 200 promptly (within the configured timeout), otherwise our system will consider that you are down and will attempt to restart the webhook (Retry).

Recommended architecture:

1. The webhook receives the JSON.
2. It validates the security signature (HMAC).
3. It inserts the raw data asynchronously into a read-optimized SQL table (or pushes it into a RabbitMQ/Kafka queue).
4. It responds HTTP 200 OK immediately.

Minimum table schema (MySQL / PostgreSQL):```sql
CREATE TABLE sms_delivery_logs (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
message_id VARCHAR(64) UNIQUE NOT NULL,
campaign_id INT NULL,
phone_number VARCHAR(20) NOT NULL,
status VARCHAR(20) NOT NULL, -- DELIVERED, FAILED, etc.
error_code VARCHAR(10) NULL,
operator VARCHAR(20) NULL,
delivered_at DATETIME NULL,
INDEX idx_status (status),
INDEX idx_campaign (campaign_id)
);

Once this data is stored in real time, you no longer need to wait for the end of the campaign to react. You can create an internal dashboard (Grafana, Metabase or a tailor-made admin panel) that monitors these 3 vital metrics:

1. The Delivery Ratio: (Nb Delivered / Total Sent) * 100. If it falls below 90%, immediate action is required.
2. Delivery Time (Latency): The time difference between the sending date and the timestamp of the DELIVERED status. If it exceeds 30 seconds for an OTP, the customer has surely already abandoned their transaction.
3. Breakdown by Operator: If 99% of Orange sends are DELIVERED but 80% of IAM sends are REJECTED, you have diagnosed a whitelisting problem at a glance.

Rather than looking at the dashboard all day, let the data alert you. Configure a script that runs every 15 minutes during your mass mailings.

If it detects an unusual peak in FAILED or REJECTED statuses (e.g.: +20% failures over the last 5 minutes), the script triggers a Slack/Teams alert or sends an emergency email to DevOps and the Marketing manager. This allows you to immediately stop a faulty campaign before burning your entire SMS budget in the void.