POST, když během hovoru
nastanou určité události — začne příchozí hovor, hovor skončí, dokončí se
spuštění hodnocení, aktivuje se upozornění a podobně. Existují dva modely
doručování:
Webhookové endpointy (doporučeno)
Více URL, tajné klíče pro jednotlivé endpointy, filtry událostí pro jednotlivé endpointy
a automatické opakování pokusů.
Správa prostřednictvím
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.Starší webhook s jedinou URL
Jedna URL pro každou organizaci. Obsahuje události životního cyklu hovorů včetně
blokujících výměn konfigurace. Správa prostřednictvím
GET/PUT /v1/webhook.telephony.incoming, telephony.complete, telephony.tool,
web.incoming, web.complete, web.tool) se také odesílá do
staršího webhooku s jedinou URL — pokud máte starší URL i odpovídající endpoint,
událost obdržíte na obou cestách. Blokující chování ( výměna konfigurace
telephony.incoming / web.incoming a odesílání
nástrojů v režimu webhooku) je
výhradně na starší cestě; každé doručení do endpointu je oznámení bez čekání na odpověď.
Formát datové části
Doručení do endpointu jsou objektem JSON sdata, event_id a
type:
event_id je jedinečné pro každou emitovanou událost. Je stejné při opakovaných pokusech
i pro každý endpoint, který událost přijme — deduplikujte podle něj.
Starší webhook s jedinou URL odesílá stejné type a data, ale
bez event_id:
Ověření podpisu
Každý požadavek obsahuje podpis HMAC-SHA256 nad nezpracovaným tělem požadavku v hlavičceX-ThunderPhone-Signature. Podepisovací klíč je
secret koncového bodu (nebo secret webhooku na úrovni vaší organizace
pro starší doručení).
Postup
- Přečtěte nezpracované tělo požadavku před jakýmkoli parsováním.
- Vypočítejte
hmac_sha256(secret, body).hexdigest(). - Porovnejte jej v konstantním čase s hlavičkou
X-ThunderPhone-Signature.
Sémantika doručování
Tato sémantika platí pro doručování do endpointů. Starší webhook s jedinou URL provádí jeden synchronní pokus bez opakování.Opakování
Opakování
Každá událost je ihned odeslána jednou. Jakákoli odpověď
2xx
potvrzuje doručení. Při jakémkoli jiném výsledku (jiném než 2xx,
chybě připojení, vypršení časového limitu) pokus zopakujeme za 1 min, 5 min, 30 min, 2 h, 6 h,
12 h a 24 h po prvním pokusu — celkem 8 pokusů během
24 hodin. Pokud selžou všechny pokusy, doručování se zastaví a endpoint
je v endpointech webhooků označen stavem
status="failing". Vraťte 2xx, jakmile je
payload trvale přijat; zpracujte jej asynchronně.Řazení
Řazení
Pořadí doručování je zajišťováno s nejlepším možným úsilím. V praxi doručujeme události v
pořadí, v jakém jsou emitovány, opakované pokusy je však při selhání mohou přeřadit.
Vždy deduplikujte a slaďte podle
call_id / ID objektu.Duplicity
Duplicity
Doručování probíhá alespoň jednou: opakovaný pokus po odpovědi, kterou jsme
neobdrželi, může událost zdvojit. Každý opakovaný pokus obsahuje stejné
event_id, proto ukládejte ID zpracovaných událostí a opakování vynechávejte. event_id je
také sdíleno mezi endpointy — dva endpointy odebírající stejnou událost obdrží stejné event_id.Časové limity
Časové limity
Doručování do endpointů má pro každý pokus časový limit 30 s. Ve
starší cestě blokující požadavky, které řídí chování probíhajícího hovoru —
výměna konfigurace
telephony.incoming / web.incoming —
vyprší po 10 s, pomalá odpověď však zpozdí přijetí hovoru, proto
se snažte odpovědět během několika sekund. Odesílání nástrojů v režimu webhooku tool dispatch umožňuje 20 s.Zdrojové IP adresy
Zdrojové IP adresy
Odchozí webhooky pocházejí z cloudového rozsahu IP adres ThunderPhone.
Pokud váš firewall vyžaduje seznam povolených adres, kontaktujte podporu a
sdělíme vám aktuální rozsahy.
Volba mezi staršími webhooky a webhooky založenými na endpointech
Nové integrace by měly zpracovávat události prostřednictvím webhooků založených na
endpointech. Starší URL ponechte (nebo přidejte) pouze tehdy, pokud
dynamicky konfigurujete hovory při přijetí nebo používáte odesílání nástrojů v režimu webhooku — tyto
výměny požadavků a odpovědí fungují pouze ve starší cestě.
Související
Katalog událostí
Všechny typy událostí a jejich payloady.
Endpointy webhooků
Spravujte více endpointů, filtry událostí a tajné klíče.
telephony.incoming / web.incoming
Blokující požadavek, na který musí váš server odpovědět, aby nakonfiguroval hovory.
telephony.complete / web.complete
Payload po hovoru s přepisem, nahrávkou a metrikami.