Points de terminaison des webhooks

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 URL par organisation.

Points de terminaison

Méthode	Chemin	Rôle requis	Description
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Lister les points de terminaison
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Créer un point de terminaison
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Mettre à jour le libellé / l’URL / les événements / le statut
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Supprimer un point de terminaison
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Envoyer une livraison de test signée

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

Champ	Type	Description
`id`	UUID	ID du point de terminaison
`label`	string	Nom d’affichage, 1 à 120 caractères
`url`	string	URL HTTPS ; `http://localhost` autorisé pour le développement
`events`	array of string	Types d’événements abonnés (voir les valeurs valides). Un tableau vide s’abonne à tous les événements
`status`	string	`active`, `disabled` (mis en pause manuellement) ou `failing` (défini automatiquement lorsqu’une livraison épuise son programme de tentatives sur 24 h sans obtenir un seul 2xx)
`secret_hint`	string	Les 4 premiers et les 4 derniers caractères du secret de signature, avec des points de suspension (`a1b2…9f0e`) — suffisant pour comparer avec le secret enregistré localement sans exposer la valeur complète
`created_at`, `updated_at`	timestamp

Le secret complet du point de terminaison est renvoyé une seule fois lors de sa création et ne l’est plus jamais. Stockez-le de façon sécurisée — si vous le perdez, supprimez le point de terminaison et recréez-le.

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 connaître la structure de la charge utile de chaque type.

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
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 dépend toujours de vous.
failing — défini automatiquement lorsqu’une livraison vers le point de terminaison épuise l’intégralité de son programme de tentatives (8 tentatives sur 24 heures) sans jamais obtenir de 2xx. Un point de terminaison défaillant 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 programme 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 requête

Champ	Type	Obligatoire	Description
`label`	string	oui	1 à 120 caractères
`url`	string	oui	URL HTTPS (`http` autorisé uniquement pour `localhost` / `127.0.0.1`)
`events`	array	non	Une valeur vide ou omise abonne à tous les événements. Doit utiliser les valeurs listées dans Types d’événements valides ; les doublons sont supprimés

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

secret est renvoyé uniquement lors de la création. Les réponses GET ultérieures incluent uniquement secret_hint. Copiez la valeur complète dans votre gestionnaire de secrets avant de fermer la réponse.

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"]
  }'

Champ	Type	Description
`label`	string
`url`	string
`events`	array
`status`	string	`active` ou `disabled`. Définissez `active` pour réactiver un endpoint que le serveur a marqué comme `failing`

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

Envoyer une livraison de test

Envoyez un événement synthétique webhook.test à un endpoint via le pipeline de livraison normal, y compris 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é, indépendamment de 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 telle que :

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

Associés

Catalogue des événements

La liste complète des valeurs events auxquelles vous pouvez vous abonner.

Vue d’ensemble des webhooks

Vérification des signatures et sémantique de livraison.

Webhooks

Function Tools

Points de terminaison des webhooks