Kas ir webhook? Kā lietotnes paziņo viena otrai

Webhook ir automātisks ziņojums, ko viens pakalpojums nosūta jūsu lietotnei tieši tad, kad kaut kas notiek. Kad klienta maksājums ir veiksmīgs, Stripe nosūta webhook uz adresi jūsu lietotnē ar ziņu „maksājums veiksmīgs, lūk, detaļas”, un jūsu lietotne reaģē — atzīmē pasūtījumu kā apmaksātu, nosūta kvīti, atver kontu. Īsumā: API ir tas, kad jūsu lietotne jautā citam pakalpojumam; webhook ir tas, kad cits pakalpojums izsauc jūsu lietotni, lai kaut ko paziņotu.

Kāpēc tas ir svarīgi, veidojot ar AI

Tiklīdz jūsu lietotne pieņem maksājumus, saņem veidlapu iesniegumus no cita rīka vai savienojas ar tādiem pakalpojumiem kā GitHub, Shopify vai kalendārs, jūs sastapsieties ar webhook. Tie parasti ir pareizais veids, kā uzzināt, ka kaut kas noticis, bet tieši šeit AI veidotas lietotnes bieži kļūdās smalki:

• Galapunkts pieņem jebkuru pieprasījumu, tāpēc ikviens var viltot notikumu „maksājums veiksmīgs”.
• Lietotne piešķir piekļuvi norēķina pārsūtīšanas lapā, nevis webhook, tāpēc cilvēki, kas agri aizver cilni, nesaņem to, par ko samaksāja, bet cilvēki, kas atrod veiksmes URL, to saņem bez maksas.
• Tas pats notikums ierodas divreiz, un klients saņem divus pasūtījumus vai divus e-pastus.

Zinot, kā webhook darbojas, varat iepriekš pieprasīt aizsardzību.

Ikdienas salīdzinājums: piegādes īsziņa

Jūs varat uzzināt, vai jūsu paka ir ierodusies, divos veidos. Varat ik pēc desmit minūtēm iet līdz priekšdurvīm pārbaudīt (tā ir aptaujāšana — jūsu lietotne atkārtoti izsauc API, lai jautātu „vai kas jauns?”). Vai kurjers var nosūtīt jums īsziņu, kad paka piegādāta (tas ir webhook).

Īsziņa ir acīmredzami labāka — ja varat tai uzticēties. Ja ikviens varētu nosūtīt jums ziņu „paka piegādāta”, jūs vēlētos kaut kādu veidu, kā pārliecināties, ka tā tiešām nākusi no kurjera. Un, ja jūsu tālrunis bija izslēgts, kad ziņa ienāca, jūs vēlētos, lai kurjers mēģina vēlreiz vēlāk. Šie divi jautājumi — pārbaude un atkārtojumi — ir lielākā daļa no tā, kas webhook padara sarežģītus.

Kā webhook darbojas soli pa solim

1. Jūs izveidojat galapunktu savā lietotnes serverī: URL, piemēram, https://yourapp.com/webhooks/stripe, kas pieņem POST pieprasījumus.
2. Jūs reģistrējat šo URL pie nodrošinātāja un izvēlaties, kurus notikumus vēlaties (piemēram, „norēķins pabeigts” un „abonements atcelts”).
3. Nodrošinātājs jums dod parakstīšanas noslēpumu. Jūs to saglabājat kā noslēpumu savā serverī — skatiet vides mainīgos un noslēpumus.
4. Notiek notikums. Nodrošinātājs nosūta HTTP pieprasījumu uz jūsu URL ar JSON saturu, kas to apraksta, un paraksta galveni.
5. Jūsu lietotne pārbauda parakstu, ieraksta notikuma ID, ātri atbild ar veiksmes kodu (200) un tikai tad veic darbu.
6. Ja jūsu lietotne neatbild ar veiksmi, daudzi nodrošinātāji mēģina vēlreiz vēlāk.

Paraksti

Paraksts pierāda, ka pieprasījums nācis no nodrošinātāja un nav mainīts. Stripe, piemēram, aprēķina HMAC (atslēgotu pirkstu nospiedumu) ar SHA-256 pār pieprasījuma saturu un laika zīmogu, izmantojot parakstīšanas noslēpumu, un nosūta to galvenē Stripe-Signature. Jūsu lietotne veic to pašu aprēķinu ar savu noslēpuma kopiju; ja rezultāti sakrīt, pieprasījums ir autentisks. Tā kā laika zīmogs arī ir parakstīts, varat noraidīt vecus pieprasījumus, ko kāds ierakstījis un vēlāk atkārto — Stripe bibliotēkas pēc noklusējuma pieļauj piecu minūšu novirzi saskaņā ar tā dokumentāciju 2026. gada septembrī.

Viena praktiska detaļa: paraksts tiek aprēķināts pēc neapstrādātā pieprasījuma satura. Ja jūsu ietvars parsē un pārformatē JSON pirms pārbaudes, pārbaude neizdodas. Tā ir ļoti bieža kļūda.

Atkārtojumi, dublikāti un secība

Nodrošinātāji atšķiras, tāpēc pārbaudiet katra dokumentāciju. Kā 2026. gada septembrī:

Stripe dokumentācija arī saka, ka notikumi netiek garantēti ierasties tādā secībā, kādā tie notika, un ka tas pats notikums dažkārt var ierasties vairāk nekā vienu reizi, tāpēc iesaka izsekot notikumu ID.

Vispārīgā mācība attiecas uz jebkuru nodrošinātāju: notikumi var ierasties novēloti, vairāk nekā vienu reizi un nepareizā secībā. Jūsu apstrādātājam jābūt idempotentam — tā pati notikuma apstrāde divreiz dod tādu pašu rezultātu kā vienreiz.

Praktisks piemērs: maksas kursa atbloķēšana

Jūs pārdodat tiešsaistes kursu. Students noklikšķina Pirkt, maksā Stripe hostētajā norēķina lapā un tiek atgriezts jūsu vietnē.

Trausls veids: paldies lapa atbloķē kursu. Ja students aizver pārlūkprogrammu pārsūtīšanas laikā, viņš samaksājis, bet piekļuves nav. Ja kāds uzmin paldies lapas URL, viņš iegūst piekļuvi, nemaksājot.

Webhook veids:

1. Kad Stripe apstiprina maksājumu, tas nosūta notikumu checkout.session.completed uz /webhooks/stripe.
2. Jūsu serveris pārbauda parakstu ar parakstīšanas noslēpumu. Ja tas neizdodas, tas atbild 400 un nedara neko.
3. Tas pārbauda, vai šis notikuma ID jau ir apstrādāts. Ja jā, tas atbild 200 un apstājas.
4. Tas saglabā notikuma ID, atbild 200 un tad piešķir studentam piekļuvi un nosūta sveiciena e-pastu.
5. Paldies lapa vienkārši saka „Maksājums saņemts — jūsu kurss parādīsies drīz” un pārbauda studenta piekļuves statusu.

Vēlāk, ja abonements tiek atcelts vai karte noraidīta, citi webhook notikumi liek jūsu lietotnei noņemt vai apturēt piekļuvi. Tā abonementu produkti paliek sinhronizēti ar norēķiniem — skatiet kas ir SaaS un kā pievienot maksājumus savai lietotnei.

Galvenie termini

• Galapunkts: URL jūsu lietotnē, kas saņem webhook.
• Notikums / saturs (payload): kas notika, un dati, kas to apraksta (parasti JSON).
• Parakstīšanas noslēpums: koplietotais noslēpums, ko izmanto parakstu pārbaudei.
• Idempotents: drošs palaist vairāk nekā vienu reizi ar tādu pašu rezultātu.
• Aptaujāšana: atkārtota jautāšana API par izmaiņām, nevis webhook gaidīšana.
• Tunelis: rīks, kas dod klēpjdatoram pagaidu publisku URL, lai webhook varētu sasniegt to izstrādes laikā.

Biežākās kļūdas un nepareizi priekšstati

• Parakstu nepārbaudīšana. Galapunkta URL nav noslēpums. Pārbaude ir tā, kas padara pieprasījumu uzticamu.
• Lēna darba veikšana pirms atbildes. E-pastu sūtīšana vai PDF ģenerēšana pirms atbildes var izraisīt noildzi, kas izraisa atkārtojumus, kas izraisa dublikātus.
• Pieņemt, ka tieši vienreiz un pareizā secībā. Ierakstiet notikumu ID un nepaļaujieties uz ierašanās secību.
• Priekšskatījuma URL izmantošana. Webhook vajag stabilu, publisku adresi. Privātie priekšskatījumi un localhost nav sasniedzami no interneta; izmantojiet publicēto URL (vai tuneli testēšanas laikā).
• Testa un tiešraides noslēpumu sajaukšana. Nodrošinātāji bieži izsniedz dažādus parakstīšanas noslēpumus testa un tiešraides režīmiem. Glabājiet abus un izmantojiet pareizo.
• Augsta riska lēmumu pieņemšana, akli uzticoties saturam. Svarīgām darbībām ir saprātīgi pēc notikuma saņemšanas no nodrošinātāja API iegūt jaunāko stāvokli.

Ko prasīt savam AI veidotājam

Pievienojiet serverī galapunktu POST /webhooks/stripe. Pārbaudiet Stripe parakstu, izmantojot neapstrādāto pieprasījuma saturu un noslēpumu STRIPE_WEBHOOK_SECRET. Noraidiet nederīgus parakstus ar 400. Saglabājiet katra notikuma ID un izlaidiet jau apstrādātos notikumus. Atbildiet 200 ātri, tad apstrādājiet checkout.session.completed, atzīmējot pasūtījumu kā apmaksātu un nosūtot kvīti. Reģistrējiet notikuma tipu. Nepiešķiriet piekļuvi no norēķina veiksmes lapas.

Pēc tam pārbaudiet: nosūtiet testa notikumu no nodrošinātāja paneļa, nosūtiet to pašu vēlreiz un nosūtiet pieprasījumu ar nepareizu parakstu. Tikai pirmajam vajadzētu kaut ko mainīt.

Webhook Mythex

Mythex neizmanto atsevišķu webhook pakalpojumu; jūs lūdzat aģentu pievienot webhook galapunktu jūsu lietotnes pašas serverī un norādīt nodrošinātājam jūsu publicēto URL, jo webhook vajag publisku adresi. Parakstīšanas noslēpums nonāk jūsu projekta noslēpumos, un, ja to mainat tiešraides lietotnē, publicējiet vēlreiz. Docs receptē webhook apstrāde ir sākuma uzvedne, un veikalu veidnes ir labs sākumpunkts lietotnēm, kas pieņem maksājumus.

Jautājumi