Skip to main content
ThunderPhone sūta HTTP POST pieprasījumus uz jūsu serveri, kad zvana laikā kaut kas notiek — sākas ienākošs zvans, zvans beidzas, tiek pabeigta novērtēšanas izpilde, tiek aktivizēts brīdinājums un tā tālāk. Ir divi piegādes modeļi:

Tīmekļa aizķeres galapunkti (ieteicams)

Vairāki URL, atsevišķi noslēpumi katram galapunktam, notikumu filtri katram galapunktam un automātiski atkārtoti mēģinājumi. Pārvaldiet, izmantojot GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Mantotā tīmekļa aizķere ar vienu URL

Viens URL katrai organizācijai. Ietver zvana dzīves cikla notikumus, tostarp bloķējošo konfigurācijas apmaiņu. Pārvalda, izmantojot GET/PUT /v1/webhook.
Visi desmit notikumu veidi notikumu katalogā tiek piegādāti, izmantojot tīmekļa aizķeres galapunktus. Seši zvana dzīves cikla notikumi (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) tiek sūtīti arī uz mantoto tīmekļa aizķeri ar vienu URL — ja jums ir gan mantotais URL, gan atbilstošs galapunkts, jūs saņemat notikumu abos ceļos. Bloķējošā darbība (telephony.incoming / web.incoming konfigurācijas apmaiņa un tīmekļa aizķeres režīma rīku izsaukšana) ir pieejama tikai mantotajā ceļā; katra piegāde uz galapunktu ir paziņojums bez atbildes gaidīšanas.

Satura formāts

Piegādes uz galapunktiem ir JSON objekts ar data, event_id un type:
event_id ir unikāls katram ģenerētajam notikumam. Tas ir identisks atkārtotos mēģinājumos un visos galapunktos, kas saņem notikumu — izmantojiet to dublikātu novēršanai. Mantotā tīmekļa aizķere ar vienu URL sūta to pašu type un data, bet bez event_id:
Pārsūtē katrs pamatteksts tiek serializēts kanoniski — atslēgas sakārtotas alfabētiski, bez atstarpēm, UTF-8. Skaisti formatētie piemēri šajā dokumentācijā ir paredzēti tikai lasāmībai. Skatiet notikumu katalogu, lai iegūtu pilnu notikumu veidu un satura lauku sarakstu.

Paraksta verifikācija

Katram pieprasījumam galvenē X-ThunderPhone-Signature ir HMAC-SHA256 paraksts, kas aprēķināts pār neapstrādāto pieprasījuma pamattekstu. Parakstīšanas atslēga ir galapunkta secret (vai jūsu organizācijas līmeņa tīmekļa aizķeres secret mantotām piegādēm).

Darbības

  1. Nolasiet neapstrādāto pieprasījuma pamattekstu pirms jebkādas parsēšanas.
  2. Aprēķiniet hmac_sha256(secret, body).hexdigest().
  3. Salīdziniet to konstantā laikā ar galveni X-ThunderPhone-Signature.
Mēs parakstām tieši tos baitus, ko nosūtām, un šie baiti ir kanoniskā JSON serializācija (sakārtotas atslēgas, kompakti atdalītāji). Tāpēc verifikācija pret neapstrādāto pamattekstu vienmēr darbojas — un, ja jūsu ietvars nodrošina tikai parsētu JSON, tā atkārtota serializācija ar sakārtotām atslēgām un kompaktiem atdalītājiem rada identiskus baitus. Abas metodes ir aprakstītas verifikācijas ceļvedī.

Piegādes semantika

Šī semantika attiecas uz galapunktu piegādēm. Mantotais viena URL webhook ir viens sinhrons mēģinājums bez atkārtotiem mēģinājumiem.
Katrs notikums tiek mēģināts piegādāt vienu reizi nekavējoties. Jebkura 2xx atbilde apstiprina piegādi. Jebkura cita rezultāta gadījumā (ne-2xx, savienojuma kļūda, noildze) atkārtojam mēģinājumu pēc 1 min, 5 min, 30 min, 2 h, 6 h, 12 h un 24 h pēc pirmā mēģinājuma — 8 mēģinājumi 24 stundu laikā. Ja visi mēģinājumi neizdodas, piegāde tiek pārtraukta un galapunktam sadaļā webhook galapunkti tiek iestatīts status="failing". Atgrieziet 2xx, tiklīdz lietderīgā slodze ir droši pieņemta; apstrādājiet to asinhroni.
Piegādes secība tiek nodrošināta pēc iespējas. Praksē notikumus piegādājam to izraisīšanas secībā, taču kļūmju gadījumā atkārtotie mēģinājumi var mainīt secību. Vienmēr noņemiet dublikātus un saskaņojiet pēc call_id / objekta id.
Piegāde ir vismaz vienu reizi: atkārtots mēģinājums pēc atbildes, kuru nesaņēmām, var dublēt notikumu. Katram atkārtotajam mēģinājumam ir tas pats event_id, tāpēc saglabājiet apstrādātos id un izlaidiet atkārtojumus. event_id ir kopīgs arī starp galapunktiem — divi galapunkti, kas abonē vienu un to pašu notikumu, saņem vienādu event_id.
Galapunktu piegādēm katram mēģinājumam ir 30 s noildze. Mantotajā ceļā bloķējošie pieprasījumi, kas nosaka aktīva zvana darbību — telephony.incoming / web.incoming konfigurācijas apmaiņa — pārsniedz noildzi pēc 10 s, taču lēna atbilde aizkavē zvana pieņemšanu, tāpēc centieties atbildēt pāris sekunžu laikā. Rīku izsaukšana webhook režīmā ļauj 20 s.
Izejošie webhook tiek sūtīti no ThunderPhone mākoņpakalpojuma IP adrešu diapazona. Ja jūsu ugunsmūrim nepieciešams atļauto saraksts, sazinieties ar atbalsta komandu, un mēs kopīgosim pašreizējos diapazonus.

Izvēle starp mantotajiem un uz galapunktiem balstītajiem webhook

Jaunajām integrācijām notikumi jāsaņem, izmantojot uz galapunktiem balstītus webhook. Saglabājiet (vai pievienojiet) mantoto URL tikai tad, ja zvanus dinamiski konfigurējat to pieņemšanas brīdī vai izmantojat rīku izsaukšanu webhook režīmā — šīs pieprasījuma/atbildes apmaiņas darbojas tikai mantotajā ceļā.

Saistītie resursi

Notikumu katalogs

Visi notikumu tipi un to lietderīgās slodzes.

Webhook galapunkti

Pārvaldiet vairākus galapunktus, notikumu filtrus un slepenās atslēgas.

telephony.incoming / web.incoming

Bloķējošais pieprasījums, uz kuru jūsu serverim jāatbild, lai konfigurētu zvanus.

telephony.complete / web.complete

Pēc zvana nosūtīta lietderīgā slodze ar transkriptu, ierakstu un metrikām.