X-ThunderPhone-Signature. Ověření nastavte jednou správně a stejnou pomocnou funkci
použijte ve všech handlerech.
Algoritmus
- Přečtěte nezpracované tělo požadavku — přesné bajty, které jsme vám odeslali metodou POST.
- Vypočítejte
hmac_sha256(secret, body).hexdigest(). - Porovnejte jej v konstantním čase s
X-ThunderPhone-Signature. (Naivní porovnání řetězců odhaluje informace o časování.)
, 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.
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.
verify() funguje beze změny, se dvěma rozdíly:
- Nástroje
GET/DELETEnemají tělo. Argumenty se předávají jako parametry dotazu a podpis se vypočítá nad prázdným bajtovým řetězcem — tedyverify(b"", sig, secret)(Python) neboverify(Buffer.alloc(0), sig, secret)(Node). Řetězec dotazu nehashujte. - 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-IDa žá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ímendpoint.headers.
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
Opětovná serializace s výchozím formátováním
Opětovná serializace s výchozím formátováním
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.Framework automaticky parsuje JSON
Framework automaticky parsuje JSON
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“.Porovnání nebezpečné z hlediska časování
Porovnání nebezpečné z hlediska časování
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ý.Nesprávný secret pro endpointy nástrojů
Nesprávný secret pro endpointy nástrojů
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.Hashování query stringu u nástrojů GET/DELETE
Hashování query stringu u nástrojů GET/DELETE
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.
Nevracení 401 při neshodě
Nevracení 401 při neshodě
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.