Skip to main content
ThunderPhone envoie des requêtes HTTP 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.
Les dix types d’événements du catalogue des événements sont transmis via les points de terminaison de webhook. Les six événements du cycle de vie des appels (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 contenant data, 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 :
Sur le réseau, chaque corps est sérialisé de manière canonique — clés triées par ordre alphabétique, sans espaces, UTF-8. Les exemples mis en forme dans cette documentation sont fournis uniquement pour faciliter la lecture. Consultez le catalogue des événements pour obtenir la liste complète des types d’événements et des champs de charge utile.

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ête X-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

  1. Lisez le corps brut de la requête avant toute analyse.
  2. Calculez hmac_sha256(secret, body).hexdigest().
  3. Comparez-le en temps constant à l’en-tête X-ThunderPhone-Signature.
Nous signons exactement les octets que nous transmettons, et ces octets correspondent à la sérialisation JSON canonique (clés triées, séparateurs compacts). La vérification sur le corps brut fonctionne donc toujours — et si votre framework ne vous fournit que le JSON analysé, le re-sérialiser avec des clés triées et des séparateurs compacts produit des octets identiques. Les deux méthodes sont décrites dans le guide de vérification.

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.
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.
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.
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.
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.
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.