Comment paramétrer des webhooks avec l’API smsmode©

Lorsque vous utilisez l’API SMS de smsmode© pour envoyer des SMS, il est souvent utile de recevoir automatiquement les réponses de ces destinataires (SMS reçus) ou d’être informé en temps réel du statut de livraison d’un message (accusé de réception). C’est ici que les webhooks entrent en jeu : ils vous permettent de recevoir des appels HTTP automatisés vers un point de terminaison de votre choix, dès qu’un événement lié à un SMS se produit.

Quels événements peut-on capter ?

Parmi les événements typiques que vous pouvez vouloir capter :

• réception d’un SMS entrant (MO – « Mobile Originated ») vers un numéro ou alias que vous avez configuré ;
• statut de livraison (DLR – « Delivery Receipt ») pour un message envoyé via l’API : remis, échec, en cours ;
• des événements, éventuellement, clics sur lien court ou désabonnement (« STOP ») si vous utilisez des fonctionnalités supplémentaires.

Pourquoi c’est important ?

• Vous pouvez avancer vers une vraie conversation : quand un client répond à votre SMS, vous pouvez prendre en compte sa réponse (ex : « Oui », « STOP », « 1 »).
• Vous améliorez la qualité du service : en recevant les statuts, vous pouvez détecter les échecs d’envoi et relancer ou tracer.
• Vous automatisez vos workflows : par exemple, déclencher une alerte dans votre CRM ou outil ticketing quand une réponse « STOP » arrive.
• Vous respectez la conformité & délivrabilité : savoir quand un SMS est refusé ou bloqué vous aide à monitorer vos campagnes.

Comment mettre en place un webhook ?

a) Créer / activer votre endpoint

• Sur votre serveur/application, définissez une URL publique sécurisée (HTTPS) capable de recevoir des requêtes POST ;
• Assurez-vous qu’elle peut traiter un format JSON (ou autre) et répondre rapidement (souvent < 300 ms) pour éviter les timeouts.

b) Paramétrer dans smsmode^© (ou via l’API)

• Dans votre espace smsmode^© ou via l’API key correspondante, indiquez cette URL comme “webhook de réception” ou “callback statut”.
• Choisissez les événements à activer (réponses, statuts, etc.).
• Vérifiez que votre URL est bien accessible depuis l’extérieur (pas de blocage firewall).

c) Bonnes pratiques de traitement

• Vérifiez l’event pour connaître le type de notification.
• Enregistrez les données dans votre base (message_id, destinataire, statut, texte) pour traçabilité.
• Répondez rapidement avec un code HTTP 200 si votre process a bien reçu le webhook, pour éviter qu’il soit renvoyé.
• Gérez les retransmissions éventuelles (par ex : un webhook envoyé deux fois).
• Sécurisez votre endpoint : authentification (token, IP autorisées…).

Cas d’usage concrets

• Relance automatique : Si un message est retourné comme “failed”, déclencher une alerte interne ou une nouvelle tentative d’envoi.
• Désabonnement automatique : Si le texte reçu est “STOP”, marquer le contact comme désabonné et ne plus envoyer de SMS marketing.
• Statistiques de délivrabilité en temps réel : Enregistrer tous les statuts « delivered » vs « undelivered » pour déclencher des rapports.
• Conversation Interactive : Lorsqu’un client répond « OUI », déclencher un workflow (ex : envoi d’un lien, attribution d’un conseiller, etc.).

Vérifications & recommandations

• Vérifiez que votre quota ou crédits API sont suffisants avant d’envoyer (pour éviter des « failed »).
• Si vous utilisez un sender ID (émetteur personnalisé), vérifiez qu’il soit conforme à la législation (France/EU).
• Assurez-vous que vos webhooks sont hautement disponibles et que vous gérez les erreurs (retours 5xx, timeouts).
• Gardez un historique des événements pour audits (ex : un destinataire a répondu mais n’a pas été pris en compte).
• Prévenez les délais : il peut y avoir quelques secondes/minutes de latence dans la livraison ou le retour.