> ## 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.
# Webhook-eindpunten
> Beheer meerdere webhook-URL's met geheimen en gebeurtenisfilters per eindpunt.
Met het endpointgebaseerde webhooksysteem kun je **meerdere**
bestemmingen per organisatie registreren, elk met een eigen geheim, eigen
status en eigen abonnement op een subset van gebeurtenistypen. Dit is
het aanbevolen model voor alle nieuwe integraties.
Vergelijk dit met de [verouderde webhook met één URL](/api-reference/organizations#legacy-single-url-webhook),
die voor achterwaartse compatibiliteit wordt behouden maar slechts één URL per
organisatie ondersteunt.
## Eindpunten
| Methode | Pad | Vereiste rol | Beschrijving |
| -------- | ---------------------------------------------------- | ------------ | ----------------------------------------------- |
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Eindpunten weergeven |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Een eindpunt maken |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Label / URL / gebeurtenissen / status bijwerken |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Een eindpunt verwijderen |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Een ondertekende testbezorging versturen |
## Eindpuntobject
```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"
}
```
| Veld | Type | Beschrijving |
| -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID | Eindpunt-ID |
| `label` | string | Weergavenaam, 1–120 tekens |
| `url` | string | HTTPS-URL; `http://localhost` toegestaan voor ontwikkeling |
| `events` | array van strings | Geabonneerde gebeurtenistypen (zie [geldige waarden](#valid-event-types)). Een lege array abonneert zich op alle gebeurtenissen |
| `status` | string | `active`, `disabled` (handmatig gepauzeerd) of `failing` (automatisch ingesteld wanneer een bezorging het herhaalschema van 24 uur doorloopt zonder ook maar één 2xx) |
| `secret_hint` | string | Eerste 4 en laatste 4 tekens van het ondertekeningsgeheim met een beletselteken (`a1b2…9f0e`) — voldoende om het geheim dat je lokaal hebt opgeslagen te controleren zonder de volledige waarde bloot te geven |
| `created_at`, `updated_at` | timestamp | |
Het volledige `secret` van het eindpunt wordt bij het maken **eenmalig**
teruggegeven en daarna nooit meer. Sla het veilig op — als je het verliest,
verwijder je het eindpunt en maak je het opnieuw.
### Geldige gebeurtenistypen
`events` wordt gevalideerd aan de hand van exact deze set — waarden buiten de lijst
geven `400` terug. Zie de [gebeurteniscatalogus](/nl/webhooks/events) voor de
payloadstructuur van elk type.
* `telephony.incoming`, `telephony.complete`, `telephony.tool`
* `web.incoming`, `web.complete`, `web.tool`
* `call.graded`
* `issue.reported`
* `test-call.completed`
* `alert.triggered`
### Eindpuntstatussen
* `active` — bezorgingen verlopen normaal.
* `disabled` — handmatig gepauzeerd via `PATCH`. Er worden geen verzoeken verstuurd. We
veranderen de status van een `disabled` eindpunt nooit; het terugzetten naar
`active` bepaal je altijd zelf.
* `failing` — automatisch ingesteld wanneer een bezorging naar het eindpunt het
volledige herhaalschema doorloopt (8 pogingen in 24 uur) zonder ooit een 2xx
te ontvangen. Een eindpunt met de status failing ontvangt geen verder verkeer.
Zodra het eindpunt is hersteld, zet je de status met `PATCH` terug op `active`;
bezorgingen waarvan het herhaalschema nog niet is verlopen, gaan verder waar ze
waren gebleven.
***
## Eindpunten weergeven
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Geeft een array met [eindpuntobjecten](#endpoint-object) terug.
***
## Een eindpunt maken
```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"]
```
### Aanvraagvelden
| Veld | Type | Verplicht | Beschrijving |
| -------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | tekenreeks | ja | 1–120 tekens |
| `url` | tekenreeks | ja | HTTPS-URL (`http` alleen toegestaan voor `localhost` / `127.0.0.1`) |
| `events` | array | nee | Leeg/weggelaten abonneert zich op alle gebeurtenissen. Moet de waarden gebruiken die in [Geldige gebeurtenistypen](#valid-event-types) staan; duplicaten worden verwijderd |
Retourneert `201 Created` met het [eindpuntobject](#endpoint-object), plus
een extra `secret`-veld op het hoogste niveau met de onbewerkte ondertekeningssleutel — een
hexadecimale tekenreeks van 48 tekens:
```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` wordt **alleen bij het aanmaken** geretourneerd. Volgende `GET`-antwoorden
bevatten alleen de `secret_hint`. Kopieer de volledige waarde naar je
geheimenbeheerder voordat je het antwoord sluit.
***
## Een eindpunt bijwerken
```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"]
}'
```
| Veld | Type | Beschrijving |
| -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `label` | tekenreeks | |
| `url` | tekenreeks | |
| `events` | array | |
| `status` | tekenreeks | `active` of `disabled`. Stel in op `active` om een eindpunt opnieuw in te schakelen dat de server als `failing` heeft gemarkeerd |
Retourneert `200 OK` met het bijgewerkte [eindpuntobject](#endpoint-object).
***
## Een testbezorging verzenden
Verzend een synthetische `webhook.test`-gebeurtenis naar één eindpunt via de normale
bezorgingspijplijn, inclusief canonieke JSON-serialisatie,
`X-ThunderPhone-Signature`, bezorgingsregistratie en registratie van nieuwe pogingen.
De test richt zich op het geselecteerde eindpunt, ongeacht het `events`-filter.
```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"
```
Het eindpunt ontvangt een envelop zoals:
```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"
}
```
De API retourneert `200 OK` na de eerste poging, zelfs als de bestemming
een fout retourneert. Controleer `success`, `status`, `response_code` en `error`
voor het bezorgingsresultaat:
```json theme={null}
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` is synthetisch en kan niet worden toegevoegd aan het `events`-
abonnement van een eindpunt. Als de eerste poging mislukt, volgt de bezorging hetzelfde
schema voor nieuwe pogingen als normale gebeurtenisbezorgingen.
***
## Een endpoint verwijderen
```bash cURL theme={null}
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Retourneert `204 No Content`. Levering aan de URL stopt onmiddellijk;
lopende nieuwe pogingen worden afgebroken.
***
## Gerelateerd
De volledige lijst met `events`-waarden waarop je je kunt abonneren.
Handtekeningverificatie en leveringssemantiek.