POST à votre serveur lorsque des événements
se produisent pendant un appel — un appel entrant commence, un appel se termine, une exécution
d’évaluation se termine, une alerte est déclenchée, etc. Il existe deux modèles
de livraison :
Points de terminaison de webhook (recommandé)
Plusieurs URL, des secrets par point de terminaison, des filtres d’événements par point de terminaison
et des nouvelles tentatives automatiques.
Gérez-les via
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Webhook historique à URL unique
Une URL par organisation. Transmet les événements du cycle de vie des appels, y compris les
échanges de configuration bloquants. Géré via
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) sont également envoyés au
webhook historique à URL unique — si vous disposez à la fois d’une URL historique et d’un
point de terminaison correspondant, vous recevez l’événement sur les deux chemins.
Le comportement bloquant (l’échange de configuration telephony.incoming / web.incoming
et la répartition des outils en
mode webhook) existe exclusivement sur le chemin historique ; chaque livraison à un
point de terminaison est une notification sans attente de réponse.
Format de la charge utile
Les livraisons aux points de terminaison sont un objet JSON contenantdata, event_id et
type :
event_id est unique pour chaque événement émis. Il est identique entre les nouvelles tentatives
et entre tous les points de terminaison qui reçoivent l’événement — utilisez-le pour dédupliquer.
Le webhook historique à URL unique envoie les mêmes type et data, mais
sans event_id :
Vérification de signature
Chaque requête contient une signature HMAC-SHA256 calculée sur le corps brut de la requête dans l’en-têteX-ThunderPhone-Signature. La clé de signature est le secret du point de terminaison (ou le secret webhook au niveau de votre organisation pour les livraisons héritées).
Étapes
- Lisez le corps brut de la requête avant toute analyse.
- Calculez
hmac_sha256(secret, body).hexdigest(). - Comparez-le en temps constant à l’en-tête
X-ThunderPhone-Signature.
Sémantique de livraison
Cette sémantique s’applique aux livraisons vers les endpoints. Le webhook historique à URL unique effectue une seule tentative synchrone, sans nouvelles tentatives.Nouvelles tentatives
Nouvelles tentatives
Chaque événement fait l’objet d’une tentative immédiate. Toute réponse
2xx
accuse réception de la livraison. Dans tout autre cas (hors 2xx,
erreur de connexion, délai d’expiration), nous effectuons une nouvelle tentative après 1 min, 5 min, 30 min, 2 h, 6 h,
12 h et 24 h après la première tentative — soit 8 tentatives sur
24 heures. Si toutes les tentatives échouent, la livraison s’arrête et l’endpoint
est marqué status="failing" dans les
endpoints de webhook. Renvoyez 2xx dès que
la charge utile est acceptée de manière durable ; traitez-la de façon asynchrone.Ordre
Ordre
L’ordre de livraison est assuré dans la mesure du possible. En pratique, nous livrons les événements dans
l’ordre de leur émission, mais les nouvelles tentatives peuvent modifier cet ordre en cas d’échec.
Dédupliquez et réconciliez toujours par
call_id / identifiant d’objet.Doublons
Doublons
La livraison est au moins une fois : une nouvelle tentative après une réponse que nous n’avons jamais
reçue peut dupliquer un événement. Chaque nouvelle tentative porte le même
event_id ; stockez donc les identifiants traités et ignorez les doublons. event_id est
également partagé entre les endpoints — deux endpoints abonnés au
même événement reçoivent le même event_id.Délais d’expiration
Délais d’expiration
Les livraisons vers les endpoints ont un délai d’expiration de 30 s par tentative. Sur le
chemin historique, les requêtes bloquantes qui pilotent le comportement des appels en direct — l’échange de
configuration
telephony.incoming / web.incoming —
expirent après 10 s, mais une réponse lente retarde la prise d’appel ;
visez donc une réponse en quelques secondes. La répartition d’outils en mode webhook
tool dispatch autorise 20 s.Adresses IP sources
Adresses IP sources
Les webhooks sortants proviennent de la plage d’adresses IP cloud de ThunderPhone.
Si votre pare-feu nécessite une liste d’autorisation, contactez le support et nous
vous communiquerons les plages actuelles.
Choisir entre les webhooks historiques et les webhooks basés sur des endpoints
Les nouvelles intégrations doivent consommer les événements via des webhooks basés sur des
endpoints. Conservez (ou ajoutez) une URL historique uniquement si vous configurez les appels
dynamiquement au moment de la prise d’appel ou utilisez la répartition d’outils en mode webhook — ces
échanges requête/réponse ne fonctionnent que sur le chemin historique.
Ressources associées
Catalogue des événements
Tous les types d’événements et leurs charges utiles.
Endpoints de webhook
Gérez plusieurs endpoints, filtres d’événements et secrets.
telephony.incoming / web.incoming
La requête bloquante à laquelle votre serveur doit répondre pour configurer les appels.
telephony.complete / web.complete
Charge utile post-appel avec transcription, enregistrement et métriques.