Skip to main content
Katram pieprasījumam, ko nosūtām uz jūsu serveri — tīmekļa āķa piegādēm un rīku galapunktu izsaukumiem — galvenē 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

  1. Nolasiet neapstrādāto pieprasījuma pamattekstu — precīzus baitus, ko jums nosūtījām ar POST.
  2. Aprēķiniet hmac_sha256(secret, body).hexdigest().
  3. Salīdziniet konstantā laikā ar X-ThunderPhone-Signature. (Naiva virkņu salīdzināšana atklāj laika informāciju.)
Mēs parakstām tieši baitus, ko pārsūtām, tāpēc neapstrādātā pamatteksta pārbaude vienmēr darbojas. Šie baiti ir arī slodzes kanoniskā JSON serializācija — atslēgas sakārtotas alfabētiski, kompakti atdalītāji (, 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.
Dodiet priekšroku neapstrādātajam pamattekstam — tas ir par vienu soli mazāk un novērš JSON skaitļu atkārtotas pārveidošanas īpatnības dažās valodās.

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 ir endpoint), 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.
Tas pats verify() palīgs darbojas bez izmaiņām, ar divām niansēm:
  1. GET / DELETE rīkiem nav pamatteksta. Argumenti tiek nodoti kā vaicājuma parametri, un paraksts tiek aprēķināts no tukšas baitu virknes — tātad verify(b"", sig, secret) (Python) vai verify(Buffer.alloc(0), sig, secret) (Node). Neveidojiet jaucējvērtību no vaicājuma virknes.
  2. 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, izmantojot endpoint.headers.
Webhook-režīma rīku nosūtīšana (rīki bez 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

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.
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”.
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.
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.
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.
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.