POST către serverul dumneavoastră atunci când se
întâmplă lucruri în timpul unui apel — începe un apel de intrare, se încheie un apel, se finalizează
o rulare de evaluare, se declanșează o alertă și așa mai departe. Există două modele
de livrare:
Endpoint-uri webhook (recomandat)
Mai multe URL-uri, secrete per endpoint, filtre de evenimente per endpoint
și reîncercări automate.
Gestionați prin
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Webhook legacy cu un singur URL
Un URL per organizație. Include evenimentele ciclului de viață al apelului, inclusiv
schimburile de configurare blocante. Gestionat la
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) sunt trimise și către
webhook-ul legacy cu un singur URL — dacă aveți atât un URL legacy, cât și un
endpoint corespunzător, primiți evenimentul pe ambele căi. Comportamentul
blocant (schimbul de configurare telephony.incoming / web.incoming
și dispecerizarea instrumentelor în modul webhook)
există exclusiv pe calea legacy; fiecare livrare către endpoint este o
notificare fire-and-forget.
Formatul încărcăturii
Livrările către endpoint-uri sunt un obiect JSON cudata, event_id și
type:
event_id este unic pentru fiecare eveniment emis. Este identic între reîncercări
și între toate endpoint-urile care primesc evenimentul — eliminați duplicatele pe baza acestuia.
Webhook-ul legacy cu un singur URL trimite același type și data, dar
fără event_id:
Verificarea semnăturii
Fiecare solicitare include o semnătură HMAC-SHA256 calculată asupra corpului brut al solicitării în antetulX-ThunderPhone-Signature. Cheia de semnare este secret al endpointului (sau secret al webhookului la nivel de organizație pentru livrările vechi).
Pași
- Citiți corpul brut al solicitării înainte de orice analiză.
- Calculați
hmac_sha256(secret, body).hexdigest(). - Comparați în timp constant cu antetul
X-ThunderPhone-Signature.
Semantica livrării
Această semantică se aplică livrărilor către endpoint-uri. Webhookul moștenit cu un singur URL constă într-o singură încercare sincronă, fără reîncercări.Reîncercări
Reîncercări
Fiecare eveniment este încercat imediat o dată. Orice răspuns
2xx
confirmă livrarea. Pentru orice alt rezultat (non-2xx,
eroare de conexiune, expirare a timpului), reîncercăm la 1 m, 5 m, 30 m, 2 h, 6 h,
12 h și 24 h după prima încercare — 8 încercări pe parcursul a
24 de ore. Dacă toate încercările eșuează, livrarea se oprește, iar endpoint-ul
este marcat cu status="failing" în
endpoint-uri webhook. Returnați 2xx imediat ce
payloadul este acceptat durabil; procesați asincron.Ordine
Ordine
Ordinea livrărilor este realizată în limita posibilului. În practică, livrăm în
ordinea în care sunt emise evenimentele, însă reîncercările pot schimba ordinea în caz de eșec.
Deduplicați întotdeauna și efectuați reconcilierea după
call_id / id-ul obiectului.Duplicate
Duplicate
Livrarea este cel puțin o dată: o reîncercare după un răspuns pe care nu l-am
primit poate duplica un eveniment. Fiecare reîncercare include același
event_id, așadar stocați id-urile procesate și ignorați repetările. event_id este
partajat și între endpoint-uri — două endpoint-uri abonate la același eveniment primesc același event_id.Expirări ale timpului
Expirări ale timpului
Livrările către endpoint-uri au o expirare a timpului de 30 s pentru fiecare încercare. Pe
calea moștenită, cererile blocante care determină comportamentul apelurilor live — schimbul de
configurare
telephony.incoming / web.incoming —
expiră după 10 s, însă un răspuns lent întârzie preluarea apelului, deci urmăriți să
răspundeți în câteva secunde. Executarea instrumentelor în modul webhook permite 20 s.IP-uri sursă
IP-uri sursă
Webhookurile trimise provin din intervalul de IP-uri cloud al ThunderPhone.
Dacă firewallul dumneavoastră necesită o listă de permisiuni, contactați suportul și vă vom
comunica intervalele curente.
Alegerea între webhookurile moștenite și cele bazate pe endpoint-uri
Integrările noi trebuie să consume evenimente prin webhookuri bazate pe
endpoint-uri. Păstrați (sau adăugați) un URL moștenit numai dacă configurați apelurile
dinamic la momentul preluării sau utilizați executarea instrumentelor în modul webhook — aceste
schimburi cerere/răspuns rulează numai pe calea moștenită.
Asociate
Catalog de evenimente
Toate tipurile de evenimente și payloadurile acestora.
Endpoint-uri webhook
Gestionați mai multe endpoint-uri, filtre de evenimente și secrete.
telephony.incoming / web.incoming
Cererea blocantă la care serverul dumneavoastră trebuie să răspundă pentru a configura apelurile.
telephony.complete / web.complete
Payload post-apel cu transcriere, înregistrare și metrici.