Points de terminaison webhook

Gérez plusieurs URL de webhook avec des secrets et des filtres d’événements par point de terminaison.

Le système de webhooks basé sur des endpoints vous permet d’enregistrer plusieurs destinations par organisation, chacune avec son propre secret, son propre statut et son propre abonnement à un sous-ensemble de types d’événements. Il s’agit du modèle recommandé pour toutes les nouvelles intégrations.

Comparez avec le webhook historique à URL unique, qui est conservé pour assurer la rétrocompatibilité, mais ne prend en charge qu’une seule URL par organisation.

Endpoints#

Objet de point de terminaison#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Types d’événements valides#

events est validé par rapport à cet ensemble exact — les valeurs absentes de la liste renvoient 400. Consultez le catalogue des événements pour la structure de la charge utile de chaque type.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (réservé ; pas encore émis)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated n’a aucun contexte d’agent et est livré uniquement aux points de terminaison à l’échelle de l’organisation.

voice.ready et voice.failed ne peuvent pas être sélectionnés explicitement. Pour les recevoir, créez un point de terminaison à l’échelle de l’organisation avec events: []. Une liste d’événements vide reçoit chaque événement pris en charge, sauf telephony.turn et web.turn, qui doivent être sélectionnés explicitement.

États des points de terminaison#

• active — les livraisons se déroulent normalement.
• disabled — mis en pause manuellement via PATCH. Aucune requête n’est envoyée. Nous ne modifions jamais le statut d’un endpoint disabled ; le rétablir à active relève toujours de votre décision.
• failing — défini automatiquement lorsqu’une livraison vers l’endpoint épuise l’intégralité de son calendrier de tentatives (8 tentatives sur 24 heures) sans jamais obtenir de réponse 2xx. Un endpoint en échec ne reçoit plus aucun trafic. Nous envoyons un e-mail aux propriétaires et administrateurs de votre organisation lorsque cela se produit, et le dashboard affiche l’endpoint en pause avec un bouton Réactiver. Une fois l’endpoint corrigé, rétablissez son statut à active avec PATCH ; les livraisons dont le calendrier de tentatives n’est pas encore épuisé reprennent là où elles s’étaient arrêtées.

Lister les points de terminaison#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Renvoie un tableau d’objets de point de terminaison. Passez ?agent_id=42 pour renvoyer uniquement les points de terminaison associés à cet agent.

Points de terminaison associés à un agent#

Les points de terminaison à l’échelle de l’organisation reçoivent chaque événement correspondant. Un point de terminaison avec agent_id reçoit uniquement les événements correspondants pour les appels traités par cet agent ; les événements sans contexte d’agent, tels que alert.triggered, ne l’atteignent jamais. Vous pouvez également créer et gérer ces points de terminaison depuis la section Webhooks du générateur d’agents.

Créer un point de terminaison#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Champs de la requête#

Renvoie 201 Created avec l’objet Endpoint mis à jour, ainsi qu’un champ secret supplémentaire de premier niveau contenant la clé de signature brute — une chaîne hexadécimale de 48 caractères :

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Mettre à jour un point de terminaison#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Renvoie 200 OK avec l’objet Endpoint mis à jour.

Renouvelez le secret de signature#

Remplacez le secret de signature d’un endpoint, par exemple s’il a été perdu ou a pu être divulgué. Pour un endpoint associé à un agent, vous pouvez également utiliser le dashboard : ouvrez la section Webhooks de l’agent et choisissez Régénérer le secret sur l’endpoint. Les endpoints à l’échelle de l’organisation sont renouvelés via l’API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Renvoie 200 OK :

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Envoyer une livraison de test#

Envoyez un événement synthétique webhook.test à un endpoint en utilisant le pipeline de livraison normal, y compris la sérialisation JSON canonique, les deux en-têtes de signature, l’enregistrement de la livraison et le suivi des tentatives. Le test cible l’endpoint sélectionné, quel que soit son filtre events.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

L'endpoint reçoit une enveloppe comme celle-ci :

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

L'API renvoie 200 OK après la première tentative, même si la destination renvoie une erreur. Consultez success, status, response_code et error pour connaître le résultat de la livraison :

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test est synthétique et ne peut pas être ajouté à l'abonnement events d'un endpoint. Si la première tentative échoue, ThunderPhone la relance une fois environ une minute plus tard, puis s'arrête ; la livraison affiche alors status: "failed" dans Déboguer les livraisons. Une livraison de test ne marque jamais l'endpoint comme failing.

Pour configurer un déclencheur à partir de la structure d'un événement réel, transmettez un event_type facultatif. La livraison reste synthétique et contient "sample": true ; les échantillons liés aux appels utilisent call_id: 0 et agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type accepte toute valeur de Types d'événements valides. L'omettre conserve le comportement générique de webhook.test.

Supprimer un endpoint#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Renvoie 204 No Content. La livraison vers l'URL s'arrête immédiatement ; les nouvelles tentatives en cours sont abandonnées.

Déboguer les livraisons#

Avant de conclure qu'un webhook n'a pas été envoyé, consultez GET /v1/developer/webhook-deliveries. Cette ressource affiche les tentatives récentes des deux systèmes de webhooks, y compris l'identifiant d'appel, l'origine de l'URL, le statut HTTP, le nombre de tentatives, la catégorie d'échec autorisée et l'heure de la prochaine tentative. Elle ne renvoie jamais la charge utile de l'événement, la transcription, le texte d'erreur stocké, le corps de la réponse ou le chemin de l'URL.

Vous pouvez également consulter le même historique récent dans Agents → sélectionner un agent → Webhooks → Livraisons récentes. Les lignes affichent le libellé de l'endpoint et l'origine de l'URL utilisée par la dernière tentative. Il s'agit d'un état opérationnel plutôt que d'un journal d'audit immuable : la suppression d'un endpoint supprime également ses lignes de livraison.

Pour une erreur 404 n8n, vérifiez d'abord que le workflow est actif, accepte POST et utilise l'URL de webhook de production plutôt que l'URL de test. Une erreur 401 ou 403 indique un problème d'authentification ou de validation de signature ; les délais d'attente indiquent une latence ou une indisponibilité de la destination ; les erreurs TLS indiquent un problème de chaîne de certificats, de nom d'hôte ou d'expiration.

Ressources associées#