Skip to main content
Každý požadavek, který odesíláme na váš server — doručení webhooku i volání koncového bodu nástroje — obsahuje podpis HMAC-SHA256 v hlavičce X-ThunderPhone-Signature. Ověření nastavte jednou správně a stejnou pomocnou funkci použijte ve všech handlerech.

Algoritmus

  1. Přečtěte nezpracované tělo požadavku — přesné bajty, které jsme vám odeslali metodou POST.
  2. Vypočítejte hmac_sha256(secret, body).hexdigest().
  3. Porovnejte jej v konstantním čase s X-ThunderPhone-Signature. (Naivní porovnání řetězců odhaluje informace o časování.)
Podepisujeme přesně ty bajty, které přenášíme, takže ověření nezpracovaného těla vždy funguje. Tyto bajty jsou také kanonickou serializací JSON datové části — klíče jsou řazeny abecedně, oddělovače jsou kompaktní (, a : bez mezer), kódování je UTF-8. To vám poskytuje druhý, zcela ekvivalentní postup, když váš framework zpřístupňuje pouze parsovaný JSON: proveďte kanonickou reserializaci a nad ní vypočítejte HMAC.
Upřednostněte nezpracované tělo — je to o jeden krok méně a vyhnete se tím zvláštnostem při opakovaném převodu čísel JSON v některých jazycích.

Který secret?

Uložte secret do správce tajemství nebo proměnné prostředí — nikdy jej necommitujte.

Referenční implementace

Všechny čtyři ověřují nezpracované tělo požadavku:

Zapojení specifické pro framework

Ověřování volání nástrojů

Když agent přímo vyvolá některý z vašich funkčních nástrojů (nástroj má endpoint), požadavek obsahuje dvě hlavičky ThunderPhone spolu s nakonfigurovanými endpoint.headers:
  • X-ThunderPhone-Call-ID — číselné ID probíhajícího hovoru.
  • X-ThunderPhone-Signature — HMAC-SHA256 s klíčem ve formě vašeho tajného klíče webhooku na úrovni organizace nad přesnými bajty těla požadavku.
Stejný pomocník verify() funguje beze změny, se dvěma rozdíly:
  1. Nástroje GET / DELETE nemají tělo. Argumenty se předávají jako parametry dotazu a podpis se vypočítá nad prázdným bajtovým řetězcem — tedy verify(b"", sig, secret) (Python) nebo verify(Buffer.alloc(0), sig, secret) (Node). Řetězec dotazu nehashujte.
  2. Organizace bez nakonfigurovaného staršího webhooku nemají tajný klíč organizace. V takovém případě volání nástrojů obsahují pouze X-ThunderPhone-Call-ID a žádnou hlavičku podpisu. Nakonfigurujte starší webhook (PUT /v1/webhook) pro získání podpisového tajného klíče, nebo ověřujte volání nástrojů vlastní hlavičkou prostřednictvím endpoint.headers.
Odesílání nástrojů v režimu webhooku (nástroje bez endpoint, doručované na webhook vaší organizace jako telephony.tool / web.tool) je běžný podepsaný webhook — platí pro něj výše uvedený standardní postup. Oba tvary požadavků najdete v dokumentaci Funkční nástroje.

Běžné chyby

Parsování těla a jeho opětovný výpis s výchozím nastavením vaší knihovny JSON (mezery po , / :, klíče v pořadí vložení) vytvoří jiné bajty a poruší HMAC. Ověřujte nezpracované tělo — nebo pokud jej musíte znovu serializovat, přesně dodržte náš kanonický formát: seřazené klíče, kompaktní oddělovače, UTF-8.
Middleware express.json() v Expressu spotřebuje stream těla a přijdete o nezpracované bajty. Použijte express.raw() přímo pro cestu webhooku, nebo nezpracované tělo uložte do bufferu v předběžném middleware. Totéž platí pro NestJS / Koa — projděte si jejich dokumentaci k „raw body“.
expected === signature v JS nebo expected == signature v Pythonu jsou porovnání závislá na časování. Použijte crypto.timingSafeEqual, respektive hmac.compare_digest. Rozdíl ve výkonu je nulový.
Přímá volání endpointů nástrojů jsou podepsána pomocí webhook secretu na úrovni organizace (GET /v1/webhook) — nikoli pomocí secretu konkrétního endpointu z /v1/developer/webhook-endpoints. Znovu použijte stejnou funkci verify(), ale ujistěte se, že pro cesty nástrojů předáváte secret organizace.
U metod nástrojů bez těla podpis pokrývá prázdný řetězec bajtů, což zachovává jeden univerzální postup: vypočítejte HMAC z nezpracovaného těla požadavku, ať je jakékoli. Hashování adresy URL nebo query stringu nikdy nebude odpovídat.
Vrácení 200 při neúspěšném ověření z handleru vytváří cíl pro replay útoky. Pokud ověření selže, vždy odpovězte jiným stavem než 2xx.

Další kroky

Přehled webhooků

Sémantika doručování, opakování, zdrojové IP adresy.

Endpointy webhooků

Spravujte více adres URL, rotujte secrety.

Function Tools

Dvě cesty volání nástrojů a tvary jejich požadavků.

Integrace nástrojů

Vytvořte kompletní integraci s podporou nástrojů od začátku do konce.