X-ThunderPhone-Signature ir HMAC-SHA256 paraksts. Pareizi ieviesiet pārbaudi vienreiz un
izmantojiet to pašu palīgfunkciju katrā apstrādātājā.
Algoritms
- Nolasiet neapstrādāto pieprasījuma pamattekstu — precīzus baitus, ko jums nosūtījām ar POST.
- Aprēķiniet
hmac_sha256(secret, body).hexdigest(). - Salīdziniet konstantā laikā ar
X-ThunderPhone-Signature. (Naiva virkņu salīdzināšana atklāj laika informāciju.)
, un : bez atstarpēm), UTF-8. Tas sniedz otru, pilnībā
ekvivalentu pieeju gadījumam, ja jūsu ietvars nodrošina tikai parsētu JSON:
veiciet kanonisku atkārtotu serializāciju un aprēķiniet tam HMAC.
Kurš noslēpums?
Glabājiet noslēpumu savā noslēpumu pārvaldniekā vai vides mainīgajā — nekad to neiekļaujiet repozitorijā.
Atsauces realizācijas
Visas četras pārbauda neapstrādāto pieprasījuma pamattekstu:Integrācija konkrētiem ietvariem
Rīku izsaukumu verificēšana
Kad balss aģents tieši izsauc kādu no jūsu funkciju rīkiem (rīkam irendpoint), pieprasījumā līdzās jūsu konfigurētajiem
endpoint.headers tiek iekļautas divas ThunderPhone galvenes:
X-ThunderPhone-Call-ID— aktīvā zvana cipariskā id.X-ThunderPhone-Signature— HMAC-SHA256, kurā kā atslēga izmantots jūsu organizācijas līmeņa webhook noslēpums, aprēķināts no precīzajiem pieprasījuma pamatteksta baitiem.
verify() palīgs darbojas bez izmaiņām, ar divām niansēm:
GET/DELETErīkiem nav pamatteksta. Argumenti tiek nodoti kā vaicājuma parametri, un paraksts tiek aprēķināts no tukšas baitu virknes — tātadverify(b"", sig, secret)(Python) vaiverify(Buffer.alloc(0), sig, secret)(Node). Neveidojiet jaucējvērtību no vaicājuma virknes.- Organizācijām bez konfigurēta mantotā webhook nav organizācijas noslēpuma.
Šādā gadījumā rīku izsaukumi ietver tikai
X-ThunderPhone-Call-ID, bet ne paraksta galveni. Konfigurējiet mantoto webhook (PUT /v1/webhook), lai iegūtu parakstīšanas noslēpumu, vai autentificējiet rīku izsaukumus ar savu galveni, izmantojotendpoint.headers.
endpoint, kas tiek piegādāti
uz jūsu organizācijas webhook kā telephony.tool / web.tool) ir parasts
parakstīts webhook — piemērojiet iepriekš norādīto standarta metodi. Abus
pieprasījumu formātus skatiet sadaļā
Funkciju rīki.
Biežākās kļūdas
Atkārtota serializēšana ar noklusējuma formatējumu
Atkārtota serializēšana ar noklusējuma formatējumu
Parsējot pamattekstu un atkārtoti serializējot to ar jūsu JSON bibliotēkas
noklusējuma iestatījumiem (atstarpes pēc
, / :, ievietošanas secībā sakārtotas atslēgas), tiek iegūti
atšķirīgi baiti un HMAC nedarbojas. Pārbaudiet neapstrādāto pamattekstu — vai arī, ja tas ir atkārtoti jāserializē,
precīzi atbilstiet mūsu kanoniskajai formai: sakārtotas atslēgas, kompakti atdalītāji, UTF-8.Framework automātiski parsē JSON
Framework automātiski parsē JSON
Express
express.json() starpprogrammatūra patērē pamatteksta plūsmu,
un jūs zaudējat neapstrādātos baitus. Izmantojiet express.raw() tieši webhook
maršrutā vai saglabājiet neapstrādāto pamattekstu buferī pirms starpprogrammatūras.
Tas pats attiecas uz NestJS / Koa — skatiet to dokumentāciju par “raw body”.Laika ziņā nedroša salīdzināšana
Laika ziņā nedroša salīdzināšana
expected === signature JS vai expected == signature
Python vidē ir salīdzināšana ar mainīgu izpildes laiku. Izmantojiet crypto.timingSafeEqual
vai attiecīgi hmac.compare_digest. Veiktspējas atšķirības
nav.Nepareizs noslēpums rīku galapunktiem
Nepareizs noslēpums rīku galapunktiem
Tiešie rīku galapunktu izsaukumi tiek parakstīti ar organizācijas līmeņa webhook
noslēpumu (
GET /v1/webhook) — nevis ar kādu atsevišķa galapunkta noslēpumu
no /v1/developer/webhook-endpoints. Atkārtoti izmantojiet to pašu verify()
funkciju, bet pārliecinieties, ka rīku maršrutos tai nododat organizācijas noslēpumu.Vaicājuma virknes jaucējkodēšana GET/DELETE rīkos
Vaicājuma virknes jaucējkodēšana GET/DELETE rīkos
Rīku metodēm bez pamatteksta paraksts aptver tukšo baitu
virkni, saglabājot vienu universālu pieeju: veidojiet HMAC neapstrādātajam pieprasījuma pamattekstam,
lai kāds tas būtu. URL vai vaicājuma virknes jaucējkods nekad nesakritīs.
401 neatgriešana neatbilstības gadījumā
401 neatgriešana neatbilstības gadījumā
Atgriežot 200, ja verifikācija neizdodas, apstrādātājs kļūst par atkārtotas atskaņošanas
uzbrukuma mērķi. Ja verifikācija neizdodas, vienmēr atbildiet ar kodu, kas nav 2xx.
Nākamās darbības
Webhook pārskats
Piegādes semantika, atkārtoti mēģinājumi, avota IP adreses.
Webhook galapunkti
Pārvaldiet vairākus URL, mainiet noslēpumus.
Funkciju rīki
Divi rīku izsaukšanas ceļi un to pieprasījumu formāti.
Rīku integrācijas
Izveidojiet pilnīgu, uz rīkiem balstītu integrāciju no sākuma līdz beigām.