Webhook-eindpunten

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, 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

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

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

Geeft een array met eindpuntobjecten terug.

Een eindpunt maken

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

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 staan; duplicaten worden verwijderd

Retourneert 201 Created met het eindpuntobject, plus een extra secret-veld op het hoogste niveau met de onbewerkte ondertekeningssleutel — een hexadecimale tekenreeks van 48 tekens:

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

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.

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.

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:

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

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

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

Evenementencatalogus

De volledige lijst met events-waarden waarop je je kunt abonneren.

Overzicht van webhooks

Handtekeningverificatie en leveringssemantiek.

Webhooks

Function Tools

Eindpunten

Eindpuntobject

Geldige gebeurtenistypen

Eindpuntstatussen

Eindpunten weergeven

Een eindpunt maken

Aanvraagvelden

Een eindpunt bijwerken

Een testbezorging verzenden

Een endpoint verwijderen

Gerelateerd

Evenementencatalogus

Overzicht van webhooks

​Eindpunten

​Eindpuntobject

​Geldige gebeurtenistypen

​Eindpuntstatussen

​Eindpunten weergeven

​Een eindpunt maken

​Aanvraagvelden

​Een eindpunt bijwerken

​Een testbezorging verzenden

​Een endpoint verwijderen

​Gerelateerd

Evenementencatalogus

Overzicht van webhooks

Eindpunten

Eindpuntobject

Geldige gebeurtenistypen

Eindpuntstatussen

Eindpunten weergeven

Een eindpunt maken

Aanvraagvelden

Een eindpunt bijwerken

Een testbezorging verzenden

Een endpoint verwijderen

Gerelateerd