Skip to main content
ThunderPhone skickar HTTP-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.
Alla tio händelsetyper i händelsekatalogen levereras via webhook-slutpunkter. De sex samtalslivscykelhändelserna (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 med data, 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:
På nätet serialiseras varje brödtext kanoniskt — nycklar sorteras alfabetiskt, utan blanksteg, UTF-8. De snyggt formaterade exemplen i den här dokumentationen är endast för läsbarhet. Se händelsekatalogen för hela listan över händelsetyper och nyttolastfält.

Signaturverifiering

Varje begäran innehåller en HMAC-SHA256-signatur av den råa begärandetexten i headern X-ThunderPhone-Signature. Signeringsnyckeln är slutpunktens secret (eller din organisationsövergripande webhook-secret för äldre leveranser).

Steg

  1. Läs den råa begärandetexten före eventuell parsning.
  2. Beräkna hmac_sha256(secret, body).hexdigest().
  3. Jämför i konstant tid med headern X-ThunderPhone-Signature.
Vi signerar exakt de byte vi skickar, och dessa byte är den kanoniska JSON-serialiseringen (sorterade nycklar, kompakta avgränsare). Därför fungerar verifiering mot den råa texten alltid — och om ditt ramverk bara ger dig parsad JSON ger omserialisering med sorterade nycklar och kompakta avgränsare identiska byte. Båda metoderna beskrivs i verifieringsguiden.

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