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

Lorsque vous utilisez l’API de smsmode pour envoyer des campagnes ou des notifications, il est essentiel de pouvoir suivre ce qu'il se passe ensuite. C’est le rôle des webhooks (aussi appelés callbacks). Ils permettent à smsmode d'envoyer automatiquement une requête HTTP vers votre serveur dès qu’un événement survient (réception d'une réponse, mise à jour d'un statut de livraison, etc.).

📡 Quels événements peut-on capter via webhook ?

Vous pouvez configurer vos webhooks pour être notifié en temps réel sur plusieurs types d'événements :

• Les accusés de réception (DLR - Delivery Receipt) : Pour savoir instantanément si votre SMS a été remis, s'il est en cours, ou s'il a échoué (erreur de numéro, téléphone éteint).

• Les réponses entrantes (MO - Mobile Originated) : Pour recevoir directement sur votre serveur les réponses envoyées par vos clients (ex: "OUI", "STOP").

• Les interactions additionnelles : Clics sur vos liens courts tracés ou demandes de désabonnement.

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 configurer un webhook ?

La mise en place s'effectue en trois grandes étapes :

1. Créer l'endpoint sur votre serveur

•  

  Développez une route publique et sécurisée (URL en HTTPS) sur votre application, capable de recevoir des requêtes POST. Cette route doit être configurée pour analyser les payloads au format JSON.

  Assurez-vous que cette URL est accessible depuis l'extérieur (pas de blocage firewall sur nos adresses IP).

2. Paramétrer l'URL dans smsmode

Une fois votre endpoint prêt, vous devez le déclarer à smsmode :

• Depuis votre interface client (Dashboard), dans la section de configuration des API/Webhooks.

• Ou directement en passant votre URL de callback en paramètre lors de votre appel API initial d'envoi de SMS.

3. Traiter l'événement (Bonnes pratiques de développement)

• Rapidité de réponse : Votre serveur doit répondre très rapidement (idéalement en moins de 300 ms) avec un code HTTP 200 OK pour confirmer la bonne réception. Si votre traitement métier est long, traitez-le de manière asynchrone (en tâche de fond).

• Gestion des timeouts : Si votre serveur ne répond pas ou renvoie une erreur (5xx), smsmode peut tenter de retransmettre le webhook. Votre code doit être capable d'identifier les doublons (idempotence) via les identifiants de message.

• Sécurité : Vous pouvez sécuriser votre endpoint en vérifiant les IP entrantes (sur demande) ou en utilisant des tokens d'authentification.

💡 Cas d'usage concrets

L'intégration des webhooks vous permet d'automatiser vos flux métiers :

• Statistiques en temps réel : Enregistrez tous les statuts (Delivered / Failed) dans votre base de données pour générer vos propres tableaux de bord de délivrabilité.

• Nettoyage de base de données : Si un accusé de réception indique un statut "Hard Bounce" (numéro non attribué), déclenchez un script pour supprimer automatiquement ce contact de votre CRM.

• Gestion des opt-outs : Dès la réception d'un webhook indiquant une réponse "STOP", mettez instantanément le client sur liste rouge dans votre outil marketing pour respecter le RGPD.

• Parcours interactifs : Si un client répond "OUI" à une proposition de rendez-vous, déclenchez une alerte vers vos conseillers ou mettez à jour le statut dans votre agenda partagé.

📝 Recommandations supplémentaires

• Historique : Conservez toujours un log (historique) complet des webhooks reçus (avec le message_id, le numéro, le statut et l'horodatage). Cela facilite grandement le débogage et les audits en cas de réclamation client.

• Latence réseau : Gardez à l'esprit que le routage télécom implique parfois des latences. Un accusé de réception peut mettre quelques secondes, voire quelques minutes, à vous parvenir après l'envoi initial.