X-ThunderPhone-Signature. Verifiera den korrekt en gång och
använd samma hjälpfunktion i varje hanterare.
Algoritmen
- Läs den råa begärandetexten — de exakta byte vi POSTade till dig.
- Beräkna
hmac_sha256(secret, body).hexdigest(). - Jämför i konstant tid med
X-ThunderPhone-Signature. (En naiv strängjämförelse läcker tidsinformation.)
, och : utan mellanslag), UTF-8. Det ger dig ett andra, helt
likvärdigt tillvägagångssätt när ditt ramverk bara exponerar parsad JSON:
serialisera om kanoniskt och beräkna HMAC för det.
Vilken hemlighet?
Lagra hemligheten i din hemlighetshanterare eller miljövariabel — committa den aldrig.
Referensimplementationer
Alla fyra verifierar den råa begärandetexten:Frameworkspecifik koppling
Verifiera verktygsanrop
När agenten anropar ett av dina funktionsverktyg direkt (verktyget har enendpoint) innehåller begäran två ThunderPhone-rubriker utöver dina
konfigurerade endpoint.headers:
X-ThunderPhone-Call-ID— det numeriska ID:t för det aktiva samtalet.X-ThunderPhone-Signature— HMAC-SHA256, med din webhook-hemlighet på organisationsnivå som nyckel, över de exakta bytevärdena i begärans brödtext.
verify()-hjälpfunktion fungerar utan ändringar, med två detaljer:
GET- /DELETE-verktyg har ingen brödtext. Argument skickas som frågeparametrar, och signaturen beräknas över den tomma bytesträngen — alltsåverify(b"", sig, secret)(Python) ellerverify(Buffer.alloc(0), sig, secret)(Node). Hasha inte frågesträngen.- Organisationer utan en konfigurerad äldre webhook har ingen
organisationshemlighet. I det fallet innehåller verktygsanrop endast
X-ThunderPhone-Call-IDoch ingen signaturrubrik. Konfigurera den äldre webhooken (PUT /v1/webhook) för att få en signeringshemlighet, eller autentisera verktygsanrop med din egen rubrik viaendpoint.headers.
endpoint, som
levereras till din organisationswebhook som telephony.tool / web.tool)
är en vanlig signerad webhook — standardreceptet ovan gäller. Se
Funktionsverktyg för båda begärandeformaten.
Vanliga fallgropar
Serialisera om med standardformatering
Serialisera om med standardformatering
Att parsa brödtexten och dumpa den igen med JSON-bibliotekets
standardinställningar (mellanslag efter
, / :, nycklar i insättningsordning) ger
andra byte och gör att HMAC:en inte fungerar. Verifiera den råa brödtexten — eller, om
du måste serialisera om, matcha vår kanoniska form exakt: sorterade
nycklar, kompakta avgränsare, UTF-8.Ramverket parsar JSON automatiskt
Ramverket parsar JSON automatiskt
Express-mellanprogrammet
express.json() förbrukar brödtextströmmen
och du förlorar de råa byten. Använd express.raw() specifikt på webhook-routen,
eller buffra den råa brödtexten i ett mellanprogram före detta.
Samma sak gäller NestJS / Koa — läs deras dokumentation om “raw body”.Tidsosäker jämförelse
Tidsosäker jämförelse
expected === signature i JS eller expected == signature i
Python är tidsvariabla jämförelser. Använd crypto.timingSafeEqual
respektive hmac.compare_digest. Prestandaskillnaden
är obefintlig.Fel hemlighet för verktygsslutpunkter
Fel hemlighet för verktygsslutpunkter
Direkta anrop till verktygsslutpunkter signeras med webhook-hemligheten
på organisationsnivå (
GET /v1/webhook) — inte med någon hemlighet per slutpunkt
från /v1/developer/webhook-endpoints. Återanvänd samma verify()
funktion, men se till att du skickar in organisationshemligheten på verktygsrutter.Hasha frågesträngen för GET/DELETE-verktyg
Hasha frågesträngen för GET/DELETE-verktyg
För verktygsmetoder utan brödtext omfattar signaturen den tomma bytesträngen,
vilket ger ett universellt recept: HMAC:a den råa begärandebrödtexten,
oavsett vad den innehåller. Att hasha URL:en eller frågesträngen kommer aldrig att matcha.
Returnerar inte 401 vid felmatchning
Returnerar inte 401 vid felmatchning
Att returnera 200 när verifieringen misslyckas gör hanteraren till ett mål för replay-attacker.
Svara alltid med annat än 2xx om verifieringen misslyckas.
Nästa steg
Översikt över webhooks
Leveranssemantik, återförsök, käll-IP-adresser.
Webhook-slutpunkter
Hantera flera URL:er, rotera hemligheter.
Funktionsverktyg
De två sökvägarna för verktygsanrop och deras begärandeformat.
Verktygsintegrationer
Bygg en komplett verktygsstödd integration från början till slut.