Envoyer un SMS depuis une application est généralement simple : votre serveur appelle une API SMS, puis reçoit une réponse. Mais cette réponse ne raconte pas nécessairement toute l’histoire. Pour comprendre ce qui se passe après l’envoi, une application doit pouvoir suivre les événements associés au message.
C’est là que les webhooks et les accusés de livraison deviennent utiles. Ils permettent à une plateforme de recevoir des mises à jour lorsqu’un message change d’état, plutôt que de supposer que la première réponse de l’API décrit le résultat final.
1. La réponse de l’API n’est que le début
Lorsqu’une API accepte une requête, cela signifie généralement que la demande a été reçue et traitée au niveau prévu par le fournisseur. Cela ne signifie pas automatiquement que le téléphone du destinataire a reçu le SMS.
Selon l’API et le réseau, le message peut ensuite être en attente, transmis à un opérateur, livré, échoué ou rester sans état final exploitable. Les noms exacts des statuts varient selon les fournisseurs : il faut donc se référer à la documentation de l’API utilisée.
Une intégration robuste distingue au minimum l’acceptation de la requête et le résultat de livraison lorsqu’un rapport de livraison est disponible.
2. À quoi sert un webhook SMS ?
Un webhook est une requête HTTP envoyée par un service vers une URL de votre application lorsqu’un événement survient. Dans le contexte SMS, il peut notamment transmettre un changement d’état ou un rapport de livraison.
Au lieu de vérifier sans cesse l’état de chaque message, votre application expose un endpoint HTTPS capable de recevoir ces notifications. Le serveur vérifie la requête, identifie le message concerné et enregistre l’événement.
Le contenu exact du webhook, les mécanismes de signature et les événements disponibles dépendent du fournisseur. Il ne faut pas supposer qu’ils sont identiques d’une API à l’autre.
3. Concevoir un endpoint fiable
Un endpoint de webhook doit être simple, sécurisé et capable de répondre rapidement.
- Utilisez HTTPS. Évitez d’exposer un endpoint de réception non chiffré.
- Vérifiez l’origine de l’événement. Utilisez le mécanisme d’authentification ou de signature prévu par le fournisseur, lorsqu’il existe.
- Validez les données reçues. Ne faites pas confiance aveuglément aux paramètres du webhook.
- Répondez rapidement. Enregistrez l’événement et déléguez les traitements plus lourds à une file d’attente.
- Journalisez les erreurs. Conservez suffisamment d’informations pour diagnostiquer les problèmes sans stocker inutilement des données sensibles.
Une architecture asynchrone aide à absorber les pics d’événements et évite que la réception d’un webhook soit bloquée par un autre composant momentanément indisponible.
4. Prévoir les événements répétés
Les systèmes de notification peuvent réessayer l’envoi d’un webhook si votre endpoint ne répond pas comme prévu. Votre application peut donc recevoir plusieurs fois une notification correspondant au même événement.
Prévoyez un traitement idempotent : recevoir deux fois le même événement ne doit pas déclencher deux fois une action métier. Lorsque le fournisseur fournit un identifiant d’événement, utilisez-le pour détecter les doublons. Sinon, définissez une stratégie adaptée aux identifiants et aux états disponibles.
Il est préférable de conserver un historique des événements plutôt que d’écraser chaque mise à jour sans trace. Cet historique aide à comprendre la chronologie d’un message lorsqu’un client signale un problème.
5. Ne confondez pas absence de rapport et échec
Un message sans rapport de livraison visible n’est pas nécessairement un message échoué. Le rapport peut être retardé, indisponible pour une route donnée ou ne pas avoir été reçu par votre application.
Votre système doit distinguer les statuts confirmés des états inconnus ou en attente. Évitez de présenter une absence de callback comme une preuve de non-livraison. Définissez plutôt une politique de suivi, une durée d’attente et une procédure de diagnostic.
6. Que faut-il surveiller ?
Pour suivre la qualité de votre intégration, mesurez notamment :
- le nombre de requêtes acceptées par l’API ;
- la proportion de messages disposant d’un état de livraison exploitable ;
- les délais entre soumission et rapport de livraison ;
- les erreurs de réception des webhooks ;
- les événements répétés et ceux impossibles à rattacher à un message ;
- les résultats par pays, opérateur ou type de message lorsque ces informations sont disponibles.
Ces indicateurs aident à séparer un problème de votre application d’un problème intervenant plus loin dans la chaîne de livraison.
7. Checklist avant la mise en production
Avant de déployer une intégration SMS, vérifiez que votre application :
- enregistre l’identifiant du message retourné par l’API ;
- expose un endpoint HTTPS protégé pour les callbacks ;
- valide et journalise les événements reçus ;
- traite les doublons sans répéter les actions métier ;
- distingue les états confirmés des états inconnus ;
- surveille les erreurs et dispose d’une procédure de diagnostic.
Les webhooks ne garantissent pas à eux seuls la livraison d’un SMS. Ils donnent à votre application une meilleure visibilité sur les événements disponibles et permettent de réagir de manière plus fiable.
Pour conclure : une intégration SMS ne s’arrête pas à l’appel API. Le suivi des événements, la gestion des erreurs et la qualité des journaux sont essentiels pour comprendre ce qui arrive réellement aux messages.