Webhook-eindpunten

Beheer meerdere webhook-URL

Met het endpointgebaseerde webhook-systeem 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.

Endpoints#

Eindpuntobject#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "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 geven 400 terug. Zie de Gebeurteniscatalogus voor de payloadstructuur van elk type.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (gereserveerd; nog niet verzonden)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated heeft geen agentcontext en wordt alleen bezorgd bij organisatiebrede eindpunten.

voice.ready en voice.failed kunnen niet expliciet worden geselecteerd. Maak een organisatiebreed eindpunt met events: [] om ze te ontvangen. Een lege lijst met gebeurtenissen ontvangt elke ondersteunde gebeurtenis, behalve telephony.turn en web.turn, die expliciet moeten worden geselecteerd.

Eindpuntstatussen#

• active — leveringen verlopen normaal.
• disabled — handmatig gepauzeerd via PATCH. Er worden geen aanvragen verzonden. We veranderen nooit de status van een disabled-endpoint; het terugzetten naar active bepaal je altijd zelf.
• failing — automatisch ingesteld wanneer een levering aan het endpoint zijn volledige herhalingsschema (8 pogingen in 24 uur) doorloopt zonder ooit een 2xx te ontvangen. Een falend endpoint ontvangt geen verder verkeer. We sturen de eigenaren en beheerders van je organisatie een e-mail wanneer dit gebeurt, en het dashboard toont het gepauzeerde endpoint met een knop Opnieuw activeren. Zodra het endpoint is hersteld, PATCH je de status terug naar active; leveringen waarvan het herhalingsschema nog niet is verlopen, gaan verder waar ze gebleven waren.

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. Geef ?agent_id=42 door om alleen eindpunten terug te geven die tot die agent zijn beperkt.

Agentgebonden eindpunten#

Organisatiebrede eindpunten ontvangen elke overeenkomende gebeurtenis. Een eindpunt met agent_id ontvangt alleen overeenkomende gebeurtenissen voor oproepen die door die agent worden afgehandeld; gebeurtenissen zonder agentcontext, zoals alert.triggered, bereiken het nooit. Je kunt deze eindpunten ook maken en beheren vanuit de sectie Webhooks van de agentbuilder.

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

Aanvraagvelden#

Retourneert 201 Created met het endpointobject plus een extra secret-veld op het hoogste niveau met de ruwe 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"
}

Werk een endpoint bij#

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 endpointobject.

Roteer het ondertekeningsgeheim#

Vervang het ondertekeningsgeheim van een endpoint, bijvoorbeeld wanneer het verloren is gegaan of mogelijk is gelekt. Voor een endpoint op agentniveau kun je ook het dashboard gebruiken: open de sectie Webhooks van de agent en kies Geheim opnieuw genereren op het endpoint. Organisatiebrede endpoints worden via de API geroteerd.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Retourneert 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Een testlevering verzenden#

Stuur een synthetische webhook.test-gebeurtenis naar één endpoint via de normale bezorgingspijplijn, inclusief canonieke JSON-serialisatie, beide handtekeningheaders, bezorgingsregistratie en administratie van nieuwe pogingen. De test richt zich op het geselecteerde endpoint, 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 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 de events- abonnering van een eindpunt. Als de eerste poging mislukt, probeert ThunderPhone het ongeveer één minuut later nog eenmaal en stopt daarna; de levering toont dan status: "failed" onder Foutopsporing van leveringen. Een testlevering markeert het eindpunt nooit als failing.

Als je een trigger wilt configureren op basis van een echte gebeurtenisvorm, geef je een optionele event_type door. De levering blijft synthetisch en bevat "sample": true; oproepgerelateerde voorbeelden gebruiken call_id: 0 en agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type accepteert elke waarde uit Geldige gebeurtenistypen. Als je deze weglaat, blijft het algemene gedrag van webhook.test behouden.

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.

Foutopsporing van leveringen#

Voordat je concludeert dat een webhook niet is verzonden, controleer je GET /v1/developer/webhook-deliveries. Deze toont recente pogingen van beide webhook-systemen, inclusief de oproep-id, URL-oorsprong, HTTP-status, aantal pogingen, toegestane foutcategorie en het tijdstip van de volgende nieuwe poging. De endpoint retourneert nooit de gebeurtenispayload, het transcript, opgeslagen fouttekst, de responsebody of het URL-pad.

Je kunt dezelfde recente geschiedenis ook bekijken in Agents → selecteer een agent → Webhooks → Recente leveringen. Rijen tonen het eindpuntlabel en de URL-oorsprong die door de meest recente poging is gebruikt. Dit is operationele status en geen onveranderlijk auditlog: als je een eindpunt verwijdert, worden ook de leveringsrijen verwijderd.

Controleer bij een n8n-404 eerst of de workflow actief is, POST accepteert en de productie-webhook-URL gebruikt in plaats van de test-URL. Een 401 of 403 wijst op authenticatie of validatie van de handtekening; time-outs wijzen op latentie of beschikbaarheid van de bestemming; TLS-fouten wijzen op de certificaatketen, hostnaam of verloopdatum.

Gerelateerd#