Skip to main content
ThunderPhone trimite solicitări HTTP 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.
Toate cele zece tipuri de evenimente din catalogul de evenimente sunt livrate prin endpoint-uri webhook. Cele șase evenimente ale ciclului de viață al apelului (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 cu data, 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:
În tranzit, fiecare corp este serializat canonic — cheile sunt sortate alfabetic, fără spații albe, în UTF-8. Exemplele formatate pentru lizibilitate din această documentație sunt doar pentru claritate. Consultați catalogul de evenimente pentru lista completă a tipurilor de evenimente și a câmpurilor încărcăturii.

Verificarea semnăturii

Fiecare solicitare include o semnătură HMAC-SHA256 calculată asupra corpului brut al solicitării în antetul X-ThunderPhone-Signature. Cheia de semnare este secret al endpointului (sau secret al webhookului la nivel de organizație pentru livrările vechi).

Pași

  1. Citiți corpul brut al solicitării înainte de orice analiză.
  2. Calculați hmac_sha256(secret, body).hexdigest().
  3. Comparați în timp constant cu antetul X-ThunderPhone-Signature.
Semnăm exact octeții pe care îi transmitem, iar aceștia reprezintă serializarea JSON canonică (chei sortate, separatori compacți). Prin urmare, verificarea pe corpul brut funcționează întotdeauna — iar dacă frameworkul dumneavoastră vă oferă doar JSON-ul analizat, reserializarea acestuia cu chei sortate și separatori compacți produce octeți identici. Ambele metode sunt prezentate în ghidul de verificare.

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