Expertise technical

Bien utiliser les webhooks de Delivery Report (DLR) : architecture et bonnes pratiques

Webhook delivery report dlr bonnes pratiques : guide technique avec exemples de code pour les développeurs au Maroc.

Dernière mise à jour : 8 juillet 2026
Bien utiliser les webhooks de Delivery Report (DLR) : architecture et bonnes pratiques

Lorsque vous soumettez un SMS via l'API, le statut `HTTP 200 OK` ne signifie absolument pas que le client a reçu le message. Il signifie simplement que la plateforme EnvoiSMS a accepté votre requête.

Pour savoir ce qui se passe "sur le terrain" (le SMS a-t-il été bloqué par IAM ? Le numéro est-il hors service ? Le téléphone est-il éteint ?), vous devez écouter le réseau. C'est le rôle critique du **Delivery Report (DLR)**. Plutôt que d'interroger la plateforme en boucle pour demander le statut (Polling) – une pratique lourde et inefficace – la méthode moderne consiste à utiliser un **Webhook**. Notre serveur "pousse" le résultat vers le vôtre dès que l'opérateur marocain nous répond. Voici comment architecturer cela.

Anatomie d'un payload DLR typique

Lorsque l'opérateur (IAM, Orange, inwi) met à jour le statut du message, notre API déclenche une requête HTTP POST vers l'URL que vous avez configurée dans votre espace client. Le payload (corps de la requête) se présente sous ce format JSON strict : ```json { "message_id": "msg_5f8b3c9a2d1e4", "phone_number": "+212600000000", "status": "DELIVERED", "operator": "INWI", "error_code": null, "timestamp": "2026-06-25T14:32:01Z", "price_mad": 0.35, "segments": 1 } ``` Les statuts possibles sont généralement : `PENDING` (En file d'attente), `DELIVERED` (Livré au terminal), `REJECTED` (Rejeté par l'opérateur, souvent un problème de [Sender ID blacklisté](/fr/blog/comment-savoir-si-votre-numero-ou-sender-id-est-blackliste-au/)) ou `FAILED` (Échec de livraison, comme un numéro invalide).

Où et comment stocker ces données pour analyse

La plus grande erreur technique est de lier la réception du webhook directement à une interface utilisateur ou à un calcul lourd. L'endpoint webhook doit répondre à notre plateforme avec un `HTTP 200` en moins de 3 secondes, sinon notre système considérera que vous êtes en panne et [tentera de relancer le webhook](/fr/blog/webhook-de-statut-de-livraison-sms-qui-ne-se-declenche-pas-guide/) (Retry). **L'architecture recommandée :** 1. Le webhook reçoit le JSON. 2. Il valide la signature de sécurité (HMAC). 3. Il insère les données brutes de façon asynchrone dans une table SQL optimisée pour la lecture (ou les pousse dans une file RabbitMQ/Kafka). 4. Il répond `HTTP 200 OK` immédiatement. **Schéma de table minimal (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) ); ```

Construire un dashboard de délivrabilité maison

Une fois ces données stockées en temps réel, vous n'avez plus besoin d'attendre la fin de campagne pour réagir. Vous pouvez créer un dashboard interne (Grafana, Metabase ou un panel d'admin sur mesure) qui surveille ces 3 métriques vitales : 1. **Le Ratio de Délivrance :** `(Nb Delivered / Total Envoye) * 100`. S'il chute sous les 90%, une action immédiate est requise. 2. **Le Délai de Livraison (Latency) :** La différence de temps entre la date d'envoi et le `timestamp` du statut `DELIVERED`. S'il dépasse 30 secondes pour un [OTP](/fr/guides/otp-authentication-maroc/), le client a sûrement déjà abandonné sa transaction. 3. **La Répartition par Opérateur :** Si 99% des envois Orange sont `DELIVERED` mais que 80% des envois IAM sont `REJECTED`, vous avez diagnostiqué un [problème de whitelisting](/fr/blog/comment-whitelister-votre-sender-id-chez-iam-orange-et-inwi/) en un coup d'œil.

Alerting automatique en cas de chute du taux de délivrance

Plutôt que de regarder le dashboard toute la journée, laissez les données vous alerter. Configurez un script qui tourne toutes les 15 minutes pendant vos envois massifs. S'il détecte un pic inhabituel de statuts `FAILED` ou `REJECTED` (ex: +20% d'échecs sur les 5 dernières minutes), le script déclenche une alerte Slack/Teams ou envoie un mail d'urgence au DevOps et au responsable Marketing. Cela permet de stopper immédiatement une campagne défectueuse avant de brûler tout votre budget SMS dans le vide.

💡 Pourquoi choisir EnvoiSMS pour votre entreprise ?

⚡

Délivrabilité Critique

Moins de 4 secondes pour vos OTP via des canaux directs opérateurs IAM, Inwi et Orange Maroc.

💰

Optimisation du Budget

WhatsApp Business API à 0,33 MAD par message. Le meilleur ROI conversationnel.

🛡️

Données Souveraines (CNDP)

Hébergement conforme aux réglementations de protection des données personnelles locales.

Articles suggérés

Formatage SMS au Maroc : Sauts de ligne, Encodage GSM-7 vs UCS-2 et Optimisation des Coûts
technical

Formatage SMS au Maroc : Sauts de ligne, Encodage GSM-7 vs UCS-2 et Optimisation des Coûts

Formatage WhatsApp Business au Maroc : Texte Enrichi, Emojis et Boutons Interactifs
technical

Formatage WhatsApp Business au Maroc : Texte Enrichi, Emojis et Boutons Interactifs

Verify API : Sécuriser les accès et optimiser le coût des OTP au Maroc
technical

Verify API : Sécuriser les accès et optimiser le coût des OTP au Maroc