Webhooks
Mis à jour le
Où : Paramètres > Intégrations > Webhooks
À quoi ça sert :
« Relayez les événements entrants vers votre propre serveur ». SyBox transmet une copie de chaque événement WhatsApp sélectionné à une adresse sur votre serveur, en temps réel. Les webhooks ne concernent que les numéros WhatsApp. Messenger, Instagram, Telegram, les e-mails et les SMS ne sont pas transmis.
Qui peut y accéder : l'administrateur principal et les membres de l'équipe ayant la permission « Gérer les numéros WhatsApp ». Pour créer un webhook ou en réactiver un qui a été suspendu, vous devez également disposer de la permission « Afficher le numéro du contact », car les copies contiennent 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é a été envoyé, remis, lu ou a échoué.
- « Réaction » : un client a réagi à un message.
- « Transcription vocale » (option supplémentaire) : une note vocale est mise en attente un court instant, jusqu'à environ deux minutes, afin d'envoyer sa transcription écrite en même temps. Elle est désactivée tant que vous ne l'activez pas.
- Allez dans Paramètres > Intégrations > Webhooks.
- Cliquez sur « Ajouter un webhook ».
- Saisissez un « Nom ».
- Saisissez l'« URL de destination ». Il doit s'agir d'« Une adresse https publique que nous pouvons joindre ». Les adresses http simples et les adresses de réseaux privés ou internes sont refusées.
- Sous « Événements », activez au moins un événement. « Message entrant » est activé par défaut.
- Facultatif : activez « Transcription vocale » pour recevoir les notes vocales avec leur texte transcrit.
- Sous « Numéros », laissez « Tous les numéros » activé pour couvrir tous les numéros WhatsApp. Ou désactivez-le et cochez uniquement 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 de la transmission des événements :
- Chaque envoi respecte le même format que les webhooks WhatsApp de Meta.
- Chaque envoi est signé avec votre clé de signature, de la même manière que Meta signe ses webhooks. Si votre serveur vérifie déjà les webhooks de Meta, il peut vérifier ceux de SyBox avec votre secret SyBox.
- Si votre serveur ne renvoie pas une réponse positive, SyBox réessaie plusieurs fois, en espaçant de plus en plus les tentatives, pendant environ une heure. Il abandonne ensuite cet événement.
- Le même événement peut parfois arriver deux fois, par exemple après un délai d'attente dépassé. Votre serveur doit gérer les doublons.
- SyBox n'a pas de bouton d'envoi de test pour les webhooks. Pour en tester un :
- Assurez-vous que le webhook est actif et couvre le numéro que vous allez utiliser.
- Envoyez un message WhatsApp à ce numéro depuis un autre téléphone.
- Revenez dans Paramètres > Intégrations > Webhooks. La fiche affiche la dernière réponse de votre serveur avec son horodatage. Une réponse réussie (par exemple « HTTP 200 ») apparaît en vert. Une erreur apparaît en rouge. « Dernier envoi : jamais » signifie que rien n'a encore été envoyé.
- Cliquez sur Modifier pour changer le nom, l'adresse, les événements ou les numéros.
- Pour remplacer la clé de signature, saisissez-en une nouvelle dans « Clé de signature ». Laissez vide pour garder la clé actuelle (« Laissez vide pour conserver la clé actuelle »).
- Cliquez sur Activer / Désactiver pour le suspendre. Les événements qui arrivent pendant cette pause sont mis en attente. Si vous le réactivez rapidement, ils seront transmis.
- 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é. Sinon, vous verrez « Données incomplètes ».
- Une adresse qui n'est pas en https public est refusée avec le message « Une adresse https publique que nous pouvons joindre ».
J'ai perdu ma clé de signature.
Elle ne pourra plus être affichée. Modifiez le webhook, saisissez un nouveau secret de votre choix dans « Clé de signature », enregistrez, et utilisez ce nouveau secret sur votre serveur.
Mon webhook ne reçoit jamais rien.
Vérifiez ces quatre points : (1) Le webhook est activé. (2) Au moins un événement est sélectionné. (3) Il couvre le bon numéro WhatsApp ou « Tous les numéros ». (4) Votre espace de travail possède bien un numéro WhatsApp connecté, car les webhooks ne transmettent que les événements WhatsApp. Regardez ensuite le résultat du dernier envoi sur la fiche.
La fiche indique une erreur en rouge du type HTTP 404 ou 500.
SyBox a bien joint votre adresse, mais votre serveur a répondu par une erreur. Vérifiez l'adresse et les journaux de votre serveur.
Je ne peux pas créer de webhook. On me dit que je n'en ai pas l'autorisation.
Pour créer un webhook ou en réactiver un, vous devez avoir à la fois « Gérer les numéros WhatsApp » et « Afficher le numéro du contact ». Demandez à votre administrateur.