Webhooks

Webhook-eindpunten

Beheer meerdere webhook-URL

Met het op eindpunten gebaseerde webhooksysteem kun je meerdere bestemmingen per organisatie registreren, elk met een eigen secret, een eigen status en een 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 behouden blijft, maar slechts één URL per organisatie ondersteunt.

Eindpunten#

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

Geldige gebeurtenistypen#

events wordt gevalideerd aan de hand van deze exacte set — waarden buiten de lijst retourneren 400. Zie Gebeurteniscatalogus voor de payloadstructuur van elk 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

Eindpuntstatussen#

• active — afleveringen verlopen normaal.
• disabled — handmatig gepauzeerd via PATCH. Er worden geen aanvragen verzonden. We wijzigen de status van een disabled eindpunt nooit; het terugzetten naar active bepaal je altijd zelf.
• failing — automatisch ingesteld wanneer een aflevering naar het eindpunt het volledige retrieschema doorloopt (8 pogingen in 24 uur) zonder ooit een 2xx te ontvangen. Een falend eindpunt ontvangt geen verder verkeer. Zodra het eindpunt is hersteld, zet je met PATCH de status terug naar active; afleveringen waarvan het retrieschema 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"

Retourneert een array met eindpuntobjecten.

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#

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

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

Retourneert 200 OK met het bijgewerkte eindpuntobject.

Een testlevering verzenden#

Verzend een synthetische webhook.test-gebeurtenis naar één eindpunt via de normale leveringspipeline, inclusief canonieke JSON-serialisatie, X-ThunderPhone-Signature, leveringsregistratie en bijhouden 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, ook als de bestemming een fout retourneert. Controleer success, status, response_code en error voor de uitkomst van de levering:

{
  "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 levering hetzelfde schema voor nieuwe pogingen als normale gebeurtenisleveringen.

Een eindpunt 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; nieuwe pogingen die al bezig zijn, worden afgebroken.

Gerelateerd#