Webhooks
Mis à jour le
Où : Paramètres > Intégrations > Webhooks
À quoi ça sert :
"Relayez les événements entrants vers votre propre serveur." SyBox envoie en temps réel une copie de chaque événement sélectionné vers une URL de votre serveur. Les événements WhatsApp arrivent dans le propre format de Meta. Les messages des clients sur Messenger, Instagram, Telegram, TikTok et le Chat en direct, ainsi que les événements de conversation (terminée, libellés, contacts, affaires, dossiers CRM), arrivent dans le propre format de SyBox. Les e-mails et les SMS ne sont pas transmis.
Qui peut y accéder : l'administrateur principal et les membres de l'équipe détenant la permission "Gérer les canaux". Pour créer un webhook ou réactiver un webhook suspendu, vous devez aussi posséder la permission "Afficher le numéro du contact", car les données transmises comprennent les vrais numéros de téléphone des clients.
Événements disponibles :
- "Message entrant" : un client a envoyé un message.
- "Statut du message" : un message envoyé est parti, a été distribué, lu ou a échoué.
- "Réaction" : un client a réagi à un message.
- "Conversation marquée comme terminée" : une conversation a été marquée comme terminée, par un membre de l'équipe, par une automatisation ou d'elle-même après le silence du client.
- "Libellé ajouté ou retiré" : un libellé a été ajouté à une conversation ou retiré de celle-ci.
- "Contact créé ou mis à jour" : un nouveau contact a été créé, ou le nom, l'e-mail ou les champs d'un contact ont changé. Une importation de contacts n'envoie pas ces événements.
- "Affaire conclue" : une affaire a été enregistrée dans une conversation.
- "Dossier CRM ouvert ou fermé" : un dossier CRM a été ouvert, ou fermé comme résolu, non résolu ou annulé. Un dossier n'appartient à aucun numéro ; seul un webhook qui couvre tous les numéros le reçoit, et non un webhook limité à certains numéros.
Les cinq derniers arrivent dans le propre format de SyBox, pour chaque canal. La page Documentation développeur présente un exemple pour chacun.
- "Transcription vocale" (option additionnelle) : le message vocal est retenu un court instant, jusqu'à environ deux minutes, afin de transmettre son texte transcrit en même temps. Elle est désactivée par défaut.
- Allez dans Paramètres > Intégrations > Webhooks.
- Cliquez sur "Ajouter un webhook".
- Renseignez un "Nom".
- Saisissez l'"URL de destination". Elle doit correspondre à "Une adresse https publique que nous pouvons joindre". Les adresses HTTP simples ainsi que les adresses réseau privées ou internes sont rejetées.
- Sous "Événements", activez au moins un type d'événement. "Message entrant" est coché par défaut.
- Facultatif : activez "Transcription vocale" pour recevoir les messages vocaux accompagnés de leur texte.
- Sous "Numéros", conservez "Tous les numéros" actif pour couvrir l'ensemble des lignes WhatsApp. Ou désactivez-le pour ne cocher que les numéros souhaités.
- Cliquez sur Enregistrer.
- Une fenêtre affiche la "Clé de signature". "Copiez-la maintenant — elle ne sera plus affichée." Enregistrez-la sur votre serveur.
À propos des envois :
- Chaque envoi respecte le format des webhooks WhatsApp de Meta.
- Chaque requête est signée avec votre clé de signature selon la même méthode que Meta. Si votre serveur valide déjà les webhooks de Meta, il peut vérifier ceux de SyBox en utilisant votre clé SyBox.
- Si votre serveur ne retourne pas un code de succès, SyBox effectue plusieurs tentatives en espaçant les délais, pendant environ une heure, avant d'abandonner l'événement.
- Un même événement peut occasionnellement arriver en double, par exemple suite à un délai d'attente dépassé. Votre serveur doit prévoir la déduplication.
- Assurez-vous que le webhook est activé. S'il est désactivé, vous voyez "Activez d'abord ce webhook."
- Sur sa carte, cliquez sur "Envoyer un événement de test". Vous voyez "Un événement de test est en cours d'envoi. Son résultat apparaîtra dans Livraisons."
- Quelques secondes plus tard, la liste "Livraisons" s'ouvre et affiche la réponse de votre serveur. La carte indique aussi la dernière réponse de votre serveur avec son horodatage. Un code de réussite (par exemple "HTTP 200") apparaît en vert. Une erreur apparaît en rouge. "Dernière livraison : jamais" signifie qu'aucun envoi n'a encore eu lieu.
Un événement de test contient "event": "test" et ne transporte aucune donnée client. Vous pouvez en envoyer un toutes les quelques secondes ; plus tôt, vous voyez "Un test a été envoyé il y a un instant. Réessayez dans quelques secondes."
- Sur la carte du webhook, cliquez sur "Livraisons".
- La liste affiche "Les 50 dernières livraisons des 7 derniers jours.", de la plus récente à la plus ancienne. Chacune indique son événement, l'heure de la tentative et son état :
- "Livré" : votre serveur a répondu avec succès.
- "En attente d'envoi" : aucune tentative n'a encore eu lieu.
- "Échec, nouvelle tentative" : votre serveur n'a pas répondu avec succès, et SyBox réessaiera plus tard.
- "Non livré" : SyBox a cessé d'essayer.
- Elle indique également le code HTTP renvoyé par votre serveur, la durée de la réponse en millisecondes et "Tentatives : [nombre]" lorsqu'il y a eu plusieurs essais. Le message lui-même n'est pas affiché.
- Pour renvoyer une livraison, cliquez sur "Renvoyer" sur une livraison à l'état "Livré" ou "Non livré". Vous voyez "Mis en file d'attente pour un nouvel envoi." Le renvoi nécessite la permission "Afficher le numéro du contact", car il renvoie les données du client.
Désactivé automatiquement :
Si votre serveur échoue de façon répétée — 20 tentatives d'affilée, pendant plus d'une heure —, SyBox désactive le webhook. La carte affiche en rouge "Désactivé automatiquement après [nombre] échecs de livraison d'affilée", et l'administrateur principal reçoit une notification, "Un webhook a été désactivé". Ses événements en attente sont conservés pendant 24 heures. Corrigez l'adresse ou votre serveur, puis réactivez le webhook : les événements en attente sont envoyés et le compteur repart de zéro.
- Cliquez sur Modifier pour ajuster le nom, l'adresse, les événements ou les numéros associés.
- Pour remplacer le secret de signature, saisissez-en un nouveau dans "Clé de signature". Laissez le champ vide pour conserver la clé actuelle ("Laissez vide pour conserver la clé actuelle").
- Cliquez sur Activer / Désactiver pour le suspendre. Les événements survenant pendant la pause sont mis en attente. Si vous le réactivez rapidement, ils seront distribués.
- Cliquez sur Supprimer, puis confirmez "Supprimer ce webhook ?".
Règles et messages :
- Le Nom et l'URL de destination sont obligatoires, et au moins un événement doit être sélectionné. À défaut, le message "Données incomplètes" s'affiche.
- Toute adresse qui n'est pas une URL HTTPS publique sera rejetée avec l'erreur "Une adresse https publique que nous pouvons joindre".
J'ai perdu ma clé de signature.
Elle ne peut plus être réaffichée. Modifiez le webhook, saisissez une nouvelle clé de votre choix dans "Clé de signature", enregistrez, puis appliquez cette nouvelle clé sur votre serveur.
Mon webhook a été désactivé alors que je n'ai rien fait.
SyBox l'a désactivé après 20 échecs d'affilée de votre serveur pendant plus d'une heure. Voir "Désactivé automatiquement" ci-dessus : réparez votre serveur, puis réactivez le webhook dans les 24 heures afin que les événements en attente soient envoyés.
Mon webhook ne reçoit jamais rien.
Cliquez d'abord sur "Envoyer un événement de test" sur sa carte et consultez "Livraisons". Contrôlez ensuite ces quatre éléments. (1) Le webhook est bien activé. (2) Au moins un événement est sélectionné. (3) Il couvre le bon numéro WhatsApp ou "Tous les numéros". (4) Le canal sur lequel le message est arrivé est pris en charge par les webhooks (WhatsApp, Messenger, Instagram, Telegram, TikTok ou Chat en direct ; pas les e-mails ni les SMS). Consultez ensuite le statut du dernier envoi sur la carte.
La carte affiche une erreur rouge comme HTTP 404 ou 500.
SyBox a réussi à joindre votre adresse, mais votre serveur a renvoyé une erreur. Contrôlez l'URL ainsi que les journaux de votre serveur.
Impossible de créer un webhook, un message indique que je n'y suis pas autorisé.
Créer un webhook ou en réactiver un requiert à la fois la permission "Gérer les canaux" et "Afficher le numéro du contact". Rapprochez-vous de votre administrateur.