> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Points de terminaison des webhooks
> 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 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](/api-reference/organizations#legacy-single-url-webhook),
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
```json theme={null}
{
"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](#valid-event-types)). 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](/fr/webhooks/events) 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
```bash cURL theme={null}
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](#endpoint-object).
***
## Créer un endpoint
```bash cURL theme={null}
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"]
}'
```
```python Python theme={null}
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](#valid-event-types) ; les doublons sont supprimés |
Renvoie `201 Created` avec l'[objet Endpoint](#endpoint-object), 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 :
```json theme={null}
{
"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
```bash cURL theme={null}
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](#endpoint-object) 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`.
```bash cURL theme={null}
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 :
```json theme={null}
{
"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 :
```json theme={null}
{
"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
```bash cURL theme={null}
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
La liste complète des valeurs `events` auxquelles vous pouvez vous abonner.
Vérification des signatures et sémantique de livraison.