POST-begäranden till din server när saker
händer under ett samtal — ett inkommande samtal startar, ett samtal avslutas, en granskningskörning slutförs, en avisering utlöses och så vidare. Det finns två leveransmodeller:
Webhook-slutpunkter (rekommenderas)
Flera URL:er, hemligheter per slutpunkt, händelsefilter per slutpunkt
och automatiska återförsök.
Hantera via
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Äldre webhook med en enda URL
En URL per organisation. Innehåller samtalslivscykelhändelserna, inklusive
de blockerande konfigurationsutbytena. Hanteras via
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) skickas också till den
äldre webhooken med en enda URL — om du har både en äldre URL och en
matchande slutpunkt får du händelsen på båda vägarna. Blockerande
beteende (konfigurationsutbytet för telephony.incoming / web.incoming
och verktygsdistribution i
webhook-läge) finns endast på den äldre vägen; varje leverans till en
slutpunkt är en fire-and-forget-avisering.
Nyttolastformat
Leveranser till slutpunkter är ett JSON-objekt meddata, event_id och
type:
event_id är unik för varje utsänd händelse. Den är identisk vid återförsök
och för varje slutpunkt som tar emot händelsen — deduplicera utifrån den.
Den äldre webhooken med en enda URL skickar samma type och data, men
utan event_id:
Signaturverifiering
Varje begäran innehåller en HMAC-SHA256-signatur av den råa begärandetexten i headernX-ThunderPhone-Signature. Signeringsnyckeln är
slutpunktens secret (eller din organisationsövergripande webhook-secret
för äldre leveranser).
Steg
- Läs den råa begärandetexten före eventuell parsning.
- Beräkna
hmac_sha256(secret, body).hexdigest(). - Jämför i konstant tid med headern
X-ThunderPhone-Signature.
Leveranssemantik
Den här semantiken gäller leveranser till ändpunkter. Den äldre webhooken med en enda URL är ett enda synkront försök utan återförsök.Återförsök
Återförsök
Varje händelse försöks levereras en gång omedelbart. Alla
2xx-svar
bekräftar leveransen. Vid alla andra utfall (icke-2xx,
anslutningsfel, timeout) försöker vi igen efter 1 min, 5 min, 30 min, 2 h, 6 h,
12 h och 24 h efter det första försöket — 8 försök under
24 timmar. Om alla försök misslyckas stoppas leveransen och ändpunkten
markeras med status="failing" i
webhook-ändpunkter. Returnera 2xx så snart som
nyttolasten har tagits emot varaktigt; bearbeta asynkront.Ordning
Ordning
Leveransordningen är bästa möjliga. I praktiken levererar vi i den
ordning händelser skickas, men återförsök kan ändra ordningen vid fel.
Deduplicera alltid och stäm av efter
call_id / objekt-id.Dubbletter
Dubbletter
Leveransen är minst en gång: ett återförsök efter ett svar som vi aldrig
såg kan duplicera en händelse. Varje återförsök har samma
event_id, så lagra bearbetade id:n och hoppa över upprepningar. event_id delas
också mellan ändpunkter — två ändpunkter som prenumererar på samma händelse får samma event_id.Timeoutar
Timeoutar
Leveranser till ändpunkter har en timeout på 30 s per försök. På den
äldre sökvägen får blockerande begäranden som styr beteendet för aktiva samtal —
konfigurationsutbytet för
telephony.incoming / web.incoming —
timeout efter 10 s, men ett långsamt svar fördröjer när samtalet besvaras,
så sikta på att svara inom ett par sekunder. Verktygsdirigering i webhook-läge
tool dispatch tillåter 20 s.Käll-IP-adresser
Käll-IP-adresser
Utgående webhooks kommer från ThunderPhones moln-IP-intervall.
Om din brandvägg kräver en tillåtelselista kontaktar du supporten så
delar vi de aktuella intervallen.
Välja mellan äldre och ändpunktsbaserade webhooks
Nya integrationer bör hantera händelser via ändpunktsbaserade
webhooks. Behåll (eller lägg till) en äldre URL endast om du konfigurerar samtal
dynamiskt när de besvaras eller använder verktygsdirigering i webhook-läge — dessa
begäran/svar-utbyten körs endast på den äldre sökvägen.
Relaterat
Händelsekatalog
Alla händelsetyper och deras nyttolaster.
Webhook-ändpunkter
Hantera flera ändpunkter, händelsefilter och hemligheter.
telephony.incoming / web.incoming
Den blockerande begäran som din server måste besvara för att konfigurera samtal.
telephony.complete / web.complete
Nyttolast efter samtalet med transkription, inspelning och mätvärden.