BreizhVoIPUn standard sait beaucoup de choses que votre logiciel métier ignore : qui appelle, qui n'a pas répondu, quel poste vient de se déconnecter. Les webhooks font le pont : à chaque événement, le standard appelle une adresse chez vous avec le détail, et votre logiciel en fait ce qu'il veut.
Ce n'est pas le module du plan d'appel
La confusion est facile, et les deux ne servent pas à la même chose.
Le module Webhook d'un plan d'appel se place à un endroit précis d'un parcours. Il attend la réponse et peut router l'appel selon ce que votre logiciel répond. Il agit pendant l'appel.
Les webhooks décrits ici sont un abonnement à des événements. Ils partent après coup, sans rien attendre, et concernent tout le standard : pas seulement les appels, mais aussi les postes, les files, les contacts, la messagerie vocale.
En résumé : le module décide, l'abonnement informe.
Les événements auxquels s'abonner
| catégorie | événements |
|---|---|
| Appels | démarré, terminé, manqué |
| Postes | connecté, déconnecté |
| Messagerie vocale | nouveau message |
| Files d'attente | agent entré, agent sorti, appelant en attente |
| Contacts | créé, modifié, supprimé |
| Postes et numéros | créé, modifié, supprimé |
Un abonnement en choisit autant qu'il veut. Mieux vaut plusieurs abonnements ciblés qu'un seul qui reçoit tout : votre logiciel n'a pas à trier, et une adresse en panne n'entraîne pas les autres.
Vérifier que l'appel vient bien de nous
C'est le point à ne pas négliger. Votre adresse est publique : n'importe qui peut lui envoyer un faux événement, et votre logiciel le croira.
Chaque envoi porte donc une signature, calculée à partir du corps du message et du secret de l'abonnement. Votre code recalcule la même signature de son côté et compare : si elle diffère, le message n'a pas été émis par nous.
Les en-têtes accompagnant chaque envoi :
| en-tête | contenu |
|---|---|
X-Webhook-Signature | la signature, préfixée de sha256= |
X-Webhook-Event | le type d'événement |
X-Webhook-Id | l'abonnement concerné |
X-Webhook-Delivery | l'identifiant unique de cet envoi |
X-Webhook-Timestamp | l'heure d'émission |
Vous pouvez aussi ajouter vos propres en-têtes à un abonnement, par exemple une clé d'API attendue par votre logiciel.
Ce qui se passe quand votre adresse ne répond pas
Le standard considère l'envoi réussi si votre serveur répond un code de succès, et il attend quinze secondes au plus.
Sinon il recommence, jusqu'à cinq fois, en espaçant les tentatives : trente secondes, puis une minute, deux, quatre, huit. Une coupure de quelques minutes chez vous ne perd donc rien.
Ces reprises ont une conséquence sur votre code : un même événement peut vous parvenir deux fois. Si votre serveur a traité l'appel mais que sa réponse s'est perdue, le standard réessaiera.
Servez-vous de X-Webhook-Delivery, unique par envoi, pour ignorer un doublon.
Sans cette précaution, un rappel automatique ou une écriture en base peuvent
être déclenchés deux fois.
Voir ce qui a été envoyé
Le bouton Logs de chaque abonnement montre les envois, le code renvoyé par votre serveur et le contenu de sa réponse. C'est là qu'on regarde quand une intégration ne se comporte pas comme prévu, plutôt que dans son propre code.
Le bouton Tester envoie un message d'essai à la demande : de quoi vérifier une adresse avant de l'utiliser, sans attendre qu'un vrai appel arrive.
Les journaux d'envoi sont conservés trente jours, puis supprimés.
Avant de brancher
Trois précautions valent d'être prises dès le premier abonnement.
Répondez vite. Votre serveur doit accuser réception, pas faire le travail pendant que le standard attend. Rangez l'événement dans une file chez vous, et traitez-le ensuite.
Commencez par un seul événement. call.ended suffit à valider toute la
chaîne, signature comprise.
Désactivez plutôt que supprimer. Un abonnement désactivé garde ses journaux et son secret, ce qui permet de reprendre sans reconfigurer votre logiciel.