X-ThunderPhone-Signature-headeren. Få verifiseringen riktig én gang,
og bruk den samme hjelpefunksjonen i hver handler.
Algoritmen
- Les den rå forespørselsteksten — de nøyaktige bytene vi POST-et til deg.
- Beregn
hmac_sha256(secret, body).hexdigest(). - Sammenlign i konstant tid med
X-ThunderPhone-Signature. (Naiv strengsammenligning lekker tidsinformasjon.)
, og : uten mellomrom), UTF-8.
Dette gir deg en annen, helt tilsvarende metode når rammeverket ditt
bare eksponerer parsede JSON-data: serialiser kanonisk på nytt og
beregn HMAC over det.
Hvilken hemmelighet?
Lagre hemmeligheten i hemmelighetshåndtereren din eller en miljøvariabel — aldri commit den.
Referanseimplementasjoner
Alle fire verifiserer den rå forespørselsteksten:Rammeverksspesifikk oppsett
Verifisere verktøykall
Når agenten kaller et av funksjonsverktøyene dine direkte (verktøyet har etendpoint), inneholder forespørselen to ThunderPhone-headere i tillegg
til de konfigurerte endpoint.headers:
X-ThunderPhone-Call-ID— den numeriske ID-en til den pågående samtalen.X-ThunderPhone-Signature— HMAC-SHA256, med webhook-hemmeligheten på organisasjonsnivå som nøkkel, over de nøyaktige byteverdiene i forespørselskroppen.
verify()-hjelperen fungerer uendret, med to særtilfeller:
GET- /DELETE-verktøy har ingen kropp. Argumenter sendes som spørringsparametere, og signaturen beregnes over den tomme byte- strengen — altsåverify(b"", sig, secret)(Python) ellerverify(Buffer.alloc(0), sig, secret)(Node). Ikke hash spørringsstrengen.- Organisasjoner uten en konfigurert eldre webhook har ingen
organisasjonshemmelighet. I så fall inneholder verktøykall bare
X-ThunderPhone-Call-IDog ingen signatur-header. Konfigurer den eldre webhooken (PUT /v1/webhook) for å få en signeringshemmelighet, eller autentiser verktøykall med din egen header viaendpoint.headers.
endpoint, levert
til organisasjonens webhook som telephony.tool / web.tool) er en vanlig
signert webhook — standardoppskriften ovenfor gjelder. Se
Funksjonsverktøy for begge forespørselsformatene.
Vanlige fallgruver
Re-serialisering med standardformatering
Re-serialisering med standardformatering
Å parse kroppen og dumpe den på nytt med JSON-bibliotekets
standardinnstillinger (mellomrom etter
, / :, innsettingsordnede nøkler) gir
andre byte og ødelegger HMAC-en. Verifiser den rå kroppen — eller hvis
du må re-serialisere, må du samsvare nøyaktig med vår kanoniske form: sorterte
nøkler, kompakte skilletegn, UTF-8.Rammeverket parser JSON automatisk
Rammeverket parser JSON automatisk
Express-mellomvaren
express.json() leser kroppstrømmen
og du mister de rå bytene. Bruk express.raw() spesifikt på webhook-
ruten, eller bufre den rå kroppen i en forhåndsmellomvare.
Det samme gjelder NestJS / Koa — se dokumentasjonen deres for «raw body».Sammenligning som ikke er timingsikker
Sammenligning som ikke er timingsikker
expected === signature i JS eller expected == signature i
Python er sammenligninger med variabel timing. Bruk crypto.timingSafeEqual
eller henholdsvis hmac.compare_digest. Ytelsesforskjellen
er ubetydelig.Feil hemmelighet for verktøyendepunkter
Feil hemmelighet for verktøyendepunkter
Direkte kall til verktøyendepunkter signeres med webhook-
hemmeligheten på organisasjonsnivå (
GET /v1/webhook) — ikke med noen hemmelighet per endepunkt
fra /v1/developer/webhook-endpoints. Gjenbruk den samme verify()-
funksjonen, men sørg for at du sender inn organisasjonshemmeligheten på verktøyruter.Hasjing av spørringsstrengen på GET/DELETE-verktøy
Hasjing av spørringsstrengen på GET/DELETE-verktøy
For verktøymetoder uten kropp dekker signaturen den tomme byte-
strengen, slik at du beholder én universell oppskrift: HMAC den rå forespørselskroppen,
uansett hva den er. Hasjing av URL-en eller spørringsstrengen vil aldri samsvare.
Ikke returnere 401 ved avvik
Ikke returnere 401 ved avvik
Å returnere 200 ved mislykket verifisering gjør behandleren til et mål for replay-
angrep. Svar alltid med en ikke-2xx-status hvis verifiseringen mislykkes.
Neste trinn
Oversikt over webhooks
Leveringssemantikk, nye forsøk, kilde-IP-er.
Webhook-endepunkter
Administrer flere URL-er, roter hemmeligheter.
Funksjonsverktøy
De to banene for verktøykall og forespørselsformatene deres.
Verktøyintegrasjoner
Bygg en komplett verktøystøttet integrasjon fra start til slutt.