Mis on webhook? Kuidas rakendused üksteisele teada annavad

Webhook on automaatne sõnum, mille üks teenus saadab su rakendusele täpselt siis, kui midagi juhtub. Kui kliendi makse õnnestub, saadab Stripe webhooki aadressile su rakenduses sõnumiga „makse õnnestus, siin on üksikasjad“, ja su rakendus reageerib — märgib tellimuse tasutuks, saadab kviitungi, avab konto. Lühidalt: API on see, kui su rakendus küsib teenuselt küsimust; webhook on see, kui teenus helistab su rakendusele, et midagi öelda.

Miks see tehisintellektiga ehitades oluline on

Kui su rakendus võtab makseid vastu, saab vormiandmeid teiselt tööriistalt või ühendub teenustega nagu GitHub, Shopify või kalender, siis puutud webhookidega kokku. Need on tavaliselt õige viis teada saada, et midagi juhtus — aga just siin on tehisintellektiga ehitatud rakendustes kõige sagedamini peenelt valesti:

• Lõpp-punkt võtab vastu iga päringu, nii et keegi võib võltsida „makse õnnestus“ sündmuse.
• Rakendus annab juurdepääsu kassa tagasisuunamise lehel webhooki asemel, nii et inimesed, kes sulgevad vahelehe varakult, ei saa seda, mille eest maksid, ja need, kes leiavad edukuse URL-i, saavad selle tasuta.
• Sama sündmus saabub kaks korda ja klient saab kaks tellimust või kaks e-kirja.

Webhookide toimimise tundmine laseb sul kaitsed juba algusest peale nõuda.

Igapäevane näide: kohaletoimetamise sõnum

Saad teada, kas pakk on kohale jõudnud, kahel viisil. Võid iga kümne minuti tagant ukse juurde kõndida, et kontrollida (see on pollimine — su rakendus kutsub korduvalt API-d, et küsida „kas on midagi uut?“). Või kuller saadab sulle sõnumi, kui pakk on kohale toimetatud (see on webhook).

Sõnum on selgelt parem — kui sa saad sellele usaldada. Kui keegi võiks saata sulle sõnumi „pakk on kohale toimetatud“, tahaksid sa mingit viisi kontrollida, et see tõesti kullerilt tuli. Ja kui su telefon oli sõnumi saabumisel välja lülitatud, tahaksid, et kuller proovib hiljem uuesti. Need kaks muret — kontrollimine ja korduskatsed — on suurel osal sellest, mis webhookid keeruliseks teeb.

Kuidas webhook samm-sammult töötab

1. Lood lõpp-punkti oma rakenduse serverisse: URL nagu https://sinurakendus.ee/webhooks/stripe, mis võtab vastu POST-päringuid.
2. Registreerid URL-i pakkujaga ja valid sündmused, mida soovid (näiteks „kassa lõpetatud“ ja „tellimus tühistatud“).
3. Pakkuja annab sulle allkirjastamissaladuse. Salvestad selle serveris saladusena — vaata keskkonnamuutujaid ja saladusi.
4. Sündmus toimub. Pakkuja saadab sinu URL-ile HTTP-päringu JSON-kehaga, mis sündmust kirjeldab, ning allkirja päisega.
5. Su rakendus kontrollib allkirja, salvestab sündmuse ID, vastab kiiresti edukusekoodiga (200) ja alles siis teeb töö.
6. Kui su rakendus ei vasta edukalt, proovivad paljud pakkujad hiljem uuesti.

Allkirjad

Allkiri tõestab, et päring tuli pakkujalt ja seda ei ole muudetud. Stripe arvutab näiteks HMAC-i (omamoodi võtmega kaetud sõrmejälje) SHA-256 abil päringu keha ja ajatempli põhjal, kasutades allkirjastamissaladust, ning saadab selle Stripe-Signature päises. Su rakendus teeb sama arvutuse oma saladuse koopiaga; kui tulemused ühtivad, on päring tõeline. Kuna ajatempel on samuti allkirjastatud, saab tagasi lükata vanad päringud, mida keegi on salvestanud ja hiljem uuesti esitab — Stripe'i teekide vaikimisi talumatus on Stripe'i dokumentatsiooni järgi seisuga september 2026 viis minutit.

Üks praktiline detail: allkiri arvutatakse toorele päringukehale. Kui su raamistik parsib ja vormindab JSON-i enne kontrollimist ümber, allkirja kontroll ebaõnnestub. See on väga levinud viga.

Kordused, dubleerimised ja järjekord

Pakkujad erinevad, seega vaata iga pakkuja dokumentatsiooni. Seisuga september 2026:

Stripe'i dokumentatsioon ütleb ka, et sündmusi ei ole garanteeritud saabumas toimumise järjekorras ning sama sündmus võib harva saabuda rohkem kui üks kord, seega soovitab ta jälgida sündmuste ID-sid.

Üldine õppetund kehtib iga pakkuja kohta: sündmused võivad saabuda hilja, rohkem kui üks kord ja valdes järjekorrast. Su käsitleja peaks olema idempotentne — sama sündmuse töötlemine kaks korda annab sama tulemuse kui üks kord.

Töötav näide: tasulise kursuse avamine

Müüd veebikursust. Õpilane klõpsab Osta, maksab Stripe'i hostitud kassa lehel ja saadetakse tagasi su saidile.

Habras viis: „aitäh“ leht avab kursuse. Kui õpilane sulgeb brauseri tagasisuunamise ajal, on ta maksnud, kuid tal ei ole ligipääsu. Kui keegi arvab aitäh-URL-i ära, saab ta ligipääsu ilma maksmata.

Webhooki viis:

1. Kui Stripe kinnitab makse, saadab ta sündmuse checkout.session.completed aadressile /webhooks/stripe.
2. Su backend kontrollib allkirja allkirjastamissaladusega. Kui see ebaõnnestub, vastab 400 ja ei tee midagi.
3. Kontrollib, kas see sündmuse ID on juba töödeldud. Kui jah, vastab 200 ja peatub.
4. Salvestab sündmuse ID, vastab 200 ja siis annab õpilasele ligipääsu ning saadab tervituskirja.
5. Aitäh-leht ütleb lihtsalt „Makse saadud — su kursus ilmub hetkega“ ja kontrollib õpilase ligipääsu olekut.

Hiljem, kui tellimus tühistatakse või kaart ebaõnnestub, ütlevad teised webhooki sündmused su rakendusele, et ligipääs tuleb eemaldada või peatada. Nii jäävad tellimustooted arveldusega sünkrooni — vaata mis on SaaS ja kuidas lisada makseid oma rakendusele.

Põhimõisted

• Lõpp-punkt: URL su rakenduses, mis võtab webhookid vastu.
• Sündmus / payload: mis juhtus ja seda kirjeldavad andmed (tavaliselt JSON).
• Allkirjastamissaladus: jagatud saladus, mida kasutatakse allkirjade kontrollimiseks.
• Idempotentne: turvaliselt mitu korda käivitatav sama tulemusega.
• Pollimine: korduv API-päringute tegemine muutuste kohta, selle asemel et oodata webhooki.
• Tunnel: tööriist, mis annab sinu sülearvutile ajutise avaliku URL-i, nii et webhookid jõuaksid arenduse ajal sinuni.

Levinud vead ja väärarusaamad

• Allkirjade mittekontrollimine. Lõpp-punkti URL ei ole saladus. Just kontroll teeb päringu usaldusväärseks.
• Aeglase töö tegemine enne vastamist. E-kirjade saatmine või PDF-ide genereerimine enne vastamist võib põhjustada ajalõpu, mis käivitab kordused, mis tekitavad dubleerimisi.
• Eeldamine, et sündmus tuleb täpselt üks kord ja järjekorras. Salvesta sündmuste ID-d ja ära looda saabumise järjekorrale.
• Eelvaate URL-i kasutamine. Webhookid vajavad stabiilset avalikku aadressi. Privaatsed eelvaated ja localhost ei ole internetist kättesaadavad; kasuta avaldatud URL-i (või tunnelit testimise ajal).
• Testi ja live-saladuste segamine. Pakkujad annavad sageli testi- ja live-režiimile erinevad allkirjastamissaladused. Hoia mõlemad ja kasuta õiget.
• Olulistes otsustes andmete pimesi usaldamine. Kõrge panusega tegevuste puhul on mõistlik pärast sündmuse saamist pakkuja API-st viimane olek uuesti tuua.

Mida paluda oma AI-ehitajalt

Lisa serverisse POST /webhooks/stripe lõpp-punkt. Kontrolli Stripe'i allkiri toorele päringukehale ja saladusele STRIPE_WEBHOOK_SECRET. Vasta kehtetute allkirjade korral 400. Salvesta iga sündmuse ID ja jäta vahele juba töödeldud sündmused. Vasta kiiresti 200-ga ja käsitle siis checkout.session.completed, märkides tellimuse tasutuks ja saates kviitungi. Logi sündmuse tüüp. Ära anna ligipääsu kassa edukuse lehelt.

Seejärel testi seda: saada testsündmus pakkuja paneelilt, saada sama uuesti ja saada päring vale allkirjaga. Ainult esimene peaks midagi muutma.

Webhookid Mythexis

Mythex ei käita eraldi webhooki teenust; palud agendil lisada webhooki lõpp-punkti oma rakenduse enda backendi ja suunad pakkuja oma avaldatud URL-ile, sest webhookid vajavad avalikku aadressi. Allkirjastamissaladus läheb sinu projekti saladustesse ja kui seda live-rakenduses muudad, avalda uuesti. Dokumentatsiooni retsept webhookide käsitlemisest sisaldab algpromptit ning poe mallid on hea lähtepunkt rakendustele, mis võtavad makseid vastu.

Küsimused