Webhooks

Points de terminaison webhook

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

Le système de webhooks basé sur des points de terminaison 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, conservé pour assurer la rétrocompatibilité, mais qui ne prend en charge qu’une seule URL par organisation.

Points de terminaison#

Objet de point de terminaison#

{
  "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"
}

Types d’événements valides#

events est validé par rapport à cet ensemble exact — les valeurs ne figurant pas dans la liste renvoient 400. Consultez le catalogue des événements pour connaître 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
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Statuts 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 point de terminaison disabled ; le rétablir sur active relève toujours de votre décision.
• failing — défini automatiquement lorsqu’une livraison vers le point de terminaison épuise l’intégralité de son calendrier de tentatives (8 tentatives sur 24 heures) sans jamais obtenir un code 2xx. Un point de terminaison en échec ne reçoit plus aucun trafic. Une fois le point de terminaison corrigé, utilisez PATCH pour rétablir son statut sur active ; 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.

Créer un endpoint#

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 ainsi qu'un champ secret supplémentaire au niveau supérieur 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 endpoint#

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.

Envoyer une livraison de test#

Envoyez un événement webhook.test synthétique à un endpoint via le pipeline de livraison normal, avec la sérialisation JSON canonique, X-ThunderPhone-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, la livraison suit le même calendrier de tentatives que les livraisons d’événements normales.

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.

Ressources associées#