Skip to main content
ThunderPhone verstuurt HTTP-POST-verzoeken naar je server wanneer er tijdens een oproep iets gebeurt — een inkomende oproep begint, een oproep eindigt, een beoordelingsrun wordt voltooid, een waarschuwing wordt geactiveerd, enzovoort. Er zijn twee bezorgmodellen:

Webhook-eindpunten (aanbevolen)

Meerdere URL’s, geheimen per eindpunt, gebeurtenisfilters per eindpunt en automatische herhalingspogingen. Beheer via GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Verouderde webhook met één URL

Eén URL per organisatie. Bevat de gebeurtenissen in de oproepcyclus, inclusief de blokkerende configuratie-uitwisselingen. Beheer via GET/PUT /v1/webhook.
Alle tien gebeurtenistypen in de gebeurteniscatalogus worden via webhook-eindpunten bezorgd. De zes gebeurtenissen in de oproepcyclus (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) worden ook naar de verouderde webhook met één URL verzonden — als je zowel een verouderde URL als een overeenkomend eindpunt hebt, ontvang je de gebeurtenis via beide paden. Blokkerend gedrag (de telephony.incoming / web.incoming-configuratie- uitwisseling en verzending van tools in webhookmodus) bestaat uitsluitend op het verouderde pad; elke bezorging aan een eindpunt is een fire-and-forgetmelding.

Payloadformaat

Bezorgingen aan eindpunten zijn een JSON-object met data, event_id en type:
event_id is uniek voor elke verzonden gebeurtenis. Het is identiek bij herhalingspogingen en bij elk eindpunt dat de gebeurtenis ontvangt — gebruik het voor deduplicatie. De verouderde webhook met één URL verzendt hetzelfde type en dezelfde data, maar zonder event_id:
Tijdens verzending wordt elke body canoniek geserialiseerd — sleutels alfabetisch gesorteerd, zonder witruimte, UTF-8. De mooi opgemaakte voorbeelden in deze documentatie zijn uitsluitend voor leesbaarheid. Bekijk de gebeurteniscatalogus voor de volledige lijst met gebeurtenis- typen en payloadvelden.

Handtekeningverificatie

Elk verzoek bevat een HMAC-SHA256-handtekening van de onbewerkte requestbody in de header X-ThunderPhone-Signature. De ondertekeningssleutel is de secret van het eindpunt (of je webhook-secret op organisatieniveau voor verouderde leveringen).

Stappen

  1. Lees de onbewerkte requestbody vóór enige parsing.
  2. Bereken hmac_sha256(secret, body).hexdigest().
  3. Vergelijk deze in constante tijd met de header X-ThunderPhone-Signature.
We ondertekenen exact de bytes die we verzenden, en die bytes zijn de canonieke JSON-serialisatie (gesorteerde sleutels, compacte scheidingstekens). Verificatie aan de hand van de onbewerkte body werkt dus altijd — en als je framework je alleen geparste JSON geeft, produceert het opnieuw serialiseren met gesorteerde sleutels en compacte scheidingstekens identieke bytes. Beide methoden worden behandeld in de verificatiehandleiding.

Afleveringssemantiek

Deze semantiek is van toepassing op leveringen via eindpunten. De verouderde webhook met één URL is één synchrone poging zonder nieuwe pogingen.
Elke gebeurtenis wordt onmiddellijk één keer geprobeerd. Elke 2xx-reactie bevestigt de aflevering. Bij elke andere uitkomst (niet-2xx, verbindingsfout, time-out) proberen we opnieuw na 1 m, 5 m, 30 m, 2 h, 6 h, 12 h en 24 h na de eerste poging — 8 pogingen verspreid over 24 uur. Als elke poging mislukt, stopt de aflevering en wordt het eindpunt gemarkeerd met status="failing" in webhookeindpunten. Retourneer 2xx zodra de payload duurzaam is geaccepteerd; verwerk asynchroon.
De aflevervolgorde gebeurt naar beste vermogen. In de praktijk leveren we in de volgorde waarin gebeurtenissen worden verzonden, maar nieuwe pogingen kunnen de volgorde wijzigen bij fouten. Dedupliceer en reconcilieer altijd op basis van call_id / object-ID.
Aflevering is minstens één keer: een nieuwe poging na een reactie die we nooit hebben gezien, kan een gebeurtenis dupliceren. Elke nieuwe poging bevat dezelfde event_id, dus sla verwerkte ID’s op en sla herhalingen over. event_id wordt ook gedeeld tussen eindpunten — twee eindpunten die zijn geabonneerd op dezelfde gebeurtenis ontvangen dezelfde event_id.
Leveringen via eindpunten hebben een time-out van 30 s per poging. Op het verouderde pad hebben blokkerende verzoeken die live oproepgedrag bepalen — de configuratie-uitwisseling telephony.incoming / web.incoming — een time-out na 10 s, maar een trage reactie vertraagt het opnemen van de oproep, dus streef ernaar binnen enkele seconden te antwoorden. Tool-dispatch in webhookmodus tool dispatch staat 20 s toe.
Uitgaande webhooks zijn afkomstig uit het cloud-IP-bereik van ThunderPhone. Als je firewall een allowlist vereist, neem dan contact op met support en we delen de huidige bereiken.

Kiezen tussen verouderde en op eindpunten gebaseerde webhooks

Nieuwe integraties moeten gebeurtenissen verwerken via op eindpunten gebaseerde webhooks. Behoud (of voeg) alleen een verouderde URL toe als je oproepen dynamisch configureert bij het opnemen of tool-dispatch in webhookmodus gebruikt — die verzoek-/reactie-uitwisselingen worden alleen uitgevoerd via het verouderde pad.

Gerelateerd

Gebeurteniscatalogus

Alle gebeurtenistypen en hun payloads.

Webhookeindpunten

Beheer meerdere eindpunten, gebeurtenisfilters en secrets.

telephony.incoming / web.incoming

Het blokkerende verzoek waarop je server moet antwoorden om oproepen te configureren.

telephony.complete / web.complete

Payload na de oproep met transcript, opname en statistieken.