Skip to main content
Hver forespørsel vi sender til serveren din — webhook-leveringer og kall til verktøyendepunkter — har en HMAC-SHA256-signatur i X-ThunderPhone-Signature-headeren. Få verifiseringen riktig én gang, og bruk den samme hjelpefunksjonen i hver handler.

Algoritmen

  1. Les den forespørselsteksten — de nøyaktige bytene vi POST-et til deg.
  2. Beregn hmac_sha256(secret, body).hexdigest().
  3. Sammenlign i konstant tid med X-ThunderPhone-Signature. (Naiv strengsammenligning lekker tidsinformasjon.)
Vi signerer nøyaktig bytene vi overfører, så verifisering av den rå forespørselsteksten fungerer alltid. Disse bytene er også den kanoniske JSON-serialiseringen av nyttelasten — nøkler sortert alfabetisk, kompakte skilletegn (, 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.
Foretrekk den rå forespørselsteksten — det er ett steg mindre og upåvirket av særegenheter ved rundturkonvertering av JSON-tall i noen språk.

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 et endpoint), 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.
Den samme verify()-hjelperen fungerer uendret, med to særtilfeller:
  1. 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) eller verify(Buffer.alloc(0), sig, secret) (Node). Ikke hash spørringsstrengen.
  2. Organisasjoner uten en konfigurert eldre webhook har ingen organisasjonshemmelighet. I så fall inneholder verktøykall bare X-ThunderPhone-Call-ID og ingen signatur-header. Konfigurer den eldre webhooken (PUT /v1/webhook) for å få en signeringshemmelighet, eller autentiser verktøykall med din egen header via endpoint.headers.
Utsending av verktøy i webhook-modus (verktøy uten et 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

Å 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.
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».
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.
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.
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.
Å 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.