Skip to main content
ThunderPhone odesílá na váš server požadavky HTTP 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.
Všech deset typů událostí v katalogu událostí je doručováno prostřednictvím webhookových endpointů. Šest událostí životního cyklu hovorů (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 s data, 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:
Při přenosu je každá datová část serializována kanonicky — klíče jsou řazeny abecedně, bez bílých znaků, v UTF-8. Příklady s formátováním v této dokumentaci slouží pouze pro lepší čitelnost. Úplný seznam typů událostí a polí datové části najdete v katalogu událostí.

Ověření podpisu

Každý požadavek obsahuje podpis HMAC-SHA256 nad nezpracovaným tělem požadavku v hlavičce X-ThunderPhone-Signature. Podepisovací klíč je secret koncového bodu (nebo secret webhooku na úrovni vaší organizace pro starší doručení).

Postup

  1. Přečtěte nezpracované tělo požadavku před jakýmkoli parsováním.
  2. Vypočítejte hmac_sha256(secret, body).hexdigest().
  3. Porovnejte jej v konstantním čase s hlavičkou X-ThunderPhone-Signature.
Podepisujeme přesně bajty, které odesíláme, a tyto bajty představují kanonickou serializaci JSON (seřazené klíče, kompaktní oddělovače). Ověření oproti nezpracovanému tělu proto vždy funguje — a pokud vám váš framework předává pouze parsovaný JSON, opětovná serializace se seřazenými klíči a kompaktními oddělovači vytvoří totožné bajty. Oba postupy jsou popsány v návodu k ověření.

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