Skip to main content
Jokaisessa palvelimellesi lähettämässämme pyynnössä — webhook-toimituksissa ja työkalupäätepisteiden kutsuissa — on HMAC-SHA256-allekirjoitus X-ThunderPhone-Signature-otsakkeessa. Toteuta varmennus oikein kerran ja käytä samaa apufunktiota jokaisessa käsittelijässä.

Algoritmi

  1. Lue pyynnön raaka runko — täsmälleen ne tavut, jotka POSTasimme sinulle.
  2. Laske hmac_sha256(secret, body).hexdigest().
  3. Vertaa sitä vakioajassa arvoon X-ThunderPhone-Signature. (Tavallinen merkkijonovertailu vuotaa ajoitustietoa.)
Allekirjoitamme täsmälleen lähettämämme tavut, joten raakarungon varmentaminen toimii aina. Nämä tavut ovat myös hyötykuorman kanoninen JSON-sarjallistus — avaimet aakkosjärjestyksessä, tiiviit erotinmerkit (, ja : ilman välilyöntejä), UTF-8. Tämä antaa sinulle toisen, täysin vastaavan tavan, kun kehyksesi tarjoaa vain jäsennetyn JSONin: sarjallista kanonisesti uudelleen ja laske sille HMAC.
Suosi raakaa runkoa — siinä on yksi vaihe vähemmän, eikä se ole altis joidenkin kielten JSON-lukujen edestakaisen muunnoksen erityispiirteille.

Mikä salaisuus?

Tallenna salaisuus salaisuuksien hallintaan tai ympäristömuuttujaan — älä koskaan commitoi sitä.

Viitetoteutukset

Kaikki neljä varmentavat pyynnön raakarungon:

Kehyskohtainen kytkentä

Työkalukutsujen varmentaminen

Kun agentti kutsuu jotakin funktiotyökaluistasi suoraan (työkalulla on endpoint), pyyntö sisältää kaksi ThunderPhone-otsaketta määritettyjen endpoint.headers-otsakkeidesi lisäksi:
  • X-ThunderPhone-Call-ID — käynnissä olevan puhelun numeerinen tunniste.
  • X-ThunderPhone-Signature — HMAC-SHA256, joka on avattu organisaatiotason webhook-salaisuudellasi, täsmälleen pyyntörungon tavujen perusteella.
Sama verify()-apuohjelma toimii sellaisenaan, mutta huomioi kaksi asiaa:
  1. GET- / DELETE-työkaluilla ei ole runkoa. Argumentit välitetään kyselyparametreina, ja allekirjoitus lasketaan tyhjälle tavumerkkijonolle — siis verify(b"", sig, secret) (Python) tai verify(Buffer.alloc(0), sig, secret) (Node). Älä tiivistä kyselymerkkijonoa.
  2. Organisaatioilla, joille ei ole määritetty vanhaa webhookia, ei ole organisaatiosalaisuutta. Tällöin työkalukutsut sisältävät vain X-ThunderPhone-Call-ID-otsakkeen eivätkä allekirjoitusotsaketta. Määritä vanha webhook (PUT /v1/webhook) saadaksesi allekirjoitussalaisuuden tai todenna työkalukutsut omalla otsakkeellasi endpoint.headers-kentän kautta.
Webhook-tilan työkalujen välitys (työkalut, joilla ei ole endpoint-määritystä ja jotka toimitetaan organisaatiosi webhookiin muodossa telephony.tool / web.tool) on tavallinen allekirjoitettu webhook — yllä oleva vakiomenettely pätee. Katso molemmat pyyntömuodot kohdasta Funktiotyökalut.

Yleiset sudenkuopat

Rungon jäsentäminen ja uudelleenkirjoittaminen JSON-kirjastosi oletusasetuksilla (välilyönnit merkkien , / : jälkeen, lisäysjärjestyksessä olevat avaimet) tuottaa eri tavut ja rikkoo HMACin. Vahvista raaka runko — tai jos sinun on sarjoitettava se uudelleen, vastaa täsmälleen kanonista muotoamme: lajitellut avaimet, tiiviit erotinmerkit, UTF-8.
Expressin express.json()-väliohjelmisto kuluttaa rungon virran ja menetät raa’at tavut. Käytä express.raw()-toimintoa erityisesti webhook-reitillä tai puskuroi raaka runko esiväliohjelmistossa. Sama koskee NestJS:ää / Koaa — tarkista niiden “raw body” -dokumentaatio.
expected === signature JS:ssä tai expected == signature Pythonissa ovat ajoitukseltaan vaihtelevia vertailuja. Käytä vastaavasti crypto.timingSafeEqual tai hmac.compare_digest-toimintoa. Suorituskykyeroa ei käytännössä ole.
Suorat työkalupäätepistekutsut allekirjoitetaan organisaatiotason webhook-salaisuudella (GET /v1/webhook) — ei millään päätepistekohtaisella salaisuudella, joka tulee polusta /v1/developer/webhook-endpoints. Käytä samaa verify() funktiota uudelleen, mutta varmista, että syötät sille organisaation salaisuuden työkalureiteillä.
Rungottomissa työkalumenetelmissä allekirjoitus kattaa tyhjän tavumerkkijonon, jolloin käytössä säilyy yksi yleispätevä toimintatapa: HMAC raakaan pyyntörunkoon, olipa se mikä tahansa. URL-osoitteen tai kyselymerkkijonon hajautus ei koskaan täsmää.
Tilakoodin 200 palauttaminen epäonnistuneessa vahvistuksessa tekee käsittelijästä toistohyökkäyksen kohteen. Vastaa aina muulla kuin 2xx-tilakoodilla, jos vahvistus epäonnistuu.

Seuraavat vaiheet

Webhookien yleiskatsaus

Toimitussemantiikka, uudelleenyritykset, lähde-IP-osoitteet.

Webhook-päätepisteet

Hallitse useita URL-osoitteita, kierrätä salaisuuksia.

Funktiotyökalut

Kaksi työkalukutsupolkua ja niiden pyyntömuodot.

Työkalintegraatiot

Rakenna täydellinen työkaluihin perustuva integraatio alusta loppuun.