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.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 metdata, 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:
Handtekeningverificatie
Elk verzoek bevat een HMAC-SHA256-handtekening van de onbewerkte requestbody in de headerX-ThunderPhone-Signature. De ondertekeningssleutel is de secret van het eindpunt (of je webhook-secret op organisatieniveau voor verouderde leveringen).
Stappen
- Lees de onbewerkte requestbody vóór enige parsing.
- Bereken
hmac_sha256(secret, body).hexdigest(). - Vergelijk deze in constante tijd met de header
X-ThunderPhone-Signature.
Afleveringssemantiek
Deze semantiek is van toepassing op leveringen via eindpunten. De verouderde webhook met één URL is één synchrone poging zonder nieuwe pogingen.Nieuwe pogingen
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.Volgorde
Volgorde
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.Duplicaten
Duplicaten
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.Time-outs
Time-outs
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.Bron-IP's
Bron-IP's
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.