X-ThunderPhone-Signature-otsakkeessa. Toteuta varmennus oikein kerran ja
käytä samaa apufunktiota jokaisessa käsittelijässä.
Algoritmi
- Lue pyynnön raaka runko — täsmälleen ne tavut, jotka POSTasimme sinulle.
- Laske
hmac_sha256(secret, body).hexdigest(). - Vertaa sitä vakioajassa arvoon
X-ThunderPhone-Signature. (Tavallinen merkkijonovertailu vuotaa ajoitustietoa.)
, 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.
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 onendpoint), 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.
verify()-apuohjelma toimii sellaisenaan, mutta huomioi kaksi asiaa:
GET- /DELETE-työkaluilla ei ole runkoa. Argumentit välitetään kyselyparametreina, ja allekirjoitus lasketaan tyhjälle tavumerkkijonolle — siisverify(b"", sig, secret)(Python) taiverify(Buffer.alloc(0), sig, secret)(Node). Älä tiivistä kyselymerkkijonoa.- 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 otsakkeellasiendpoint.headers-kentän kautta.
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
Uudelleensarjoittaminen oletusmuotoilulla
Uudelleensarjoittaminen oletusmuotoilulla
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.Kehys jäsentää JSONin automaattisesti
Kehys jäsentää JSONin automaattisesti
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.Ajoitukselle altis vertailu
Ajoitukselle altis vertailu
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.Väärä salaisuus työkalupäätepisteille
Väärä salaisuus työkalupäätepisteille
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ä.Kyselymerkkijonon hajauttaminen GET/DELETE-työkaluissa
Kyselymerkkijonon hajauttaminen GET/DELETE-työkaluissa
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ää.
401-tilakoodin palauttamatta jättäminen ristiriitatilanteessa
401-tilakoodin palauttamatta jättäminen ristiriitatilanteessa
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.