Kaj je webhook? Kako aplikacije obveščajo druga drugo

Webhook je samodejno sporočilo, ki ga ena storitev pošlje vaši aplikaciji takoj, ko se nekaj zgodi. Ko se plačilo stranke uspešno izvede, Stripe pošlje webhook na naslov v vaši aplikaciji z obvestilom »plačilo uspešno, tukaj so podrobnosti«, vaša aplikacija pa se nanj odzove — označi naročilo kot plačano, pošlje račun, odklene račun. Na kratko: API je, ko vaša aplikacija drugi storitvi zastavi vprašanje; webhook je, ko druga storitev pokliče vašo aplikacijo in ji nekaj sporoči.

Zakaj je to pomembno pri gradnji z AI

Ko vaša aplikacija sprejema plačila, prejema oddane obrazce iz drugega orodja ali se povezuje s storitvami, kot so GitHub, Shopify ali koledar, boste naleteli na webhooke. So običajno pravilen način, da izvste, da se je nekaj zgodilo — vendar so tudi mesto, kjer so aplikacije, zgrajene z AI, najpogosteje rahlo narobe:

• Končna točka sprejme vsako zahtevo, zato lahko kdorkoli ponaredi dogodek »plačilo uspešno«.
• Aplikacija dostop odobri na strani za preusmeritev po plačilu namesto na webhooku, zato ljudje, ki zaprejo zavihek prezgodaj, ne dobijo tistega, kar so plačali, ljudje, ki najdejo naslov strani za uspeh, pa to dobijo brezplačno.
• Isti dogodek pride dvakrat, zato stranka dobi dve naročili ali dve e-pošti.

Če poznate delovanje webhookov, lahko zaščito zahtevate že vnaprej.

Vsakdanja primerjava: sporočilo o dostavi

Za to, ali je vaša pošiljka prispela, lahko izveste na dva načina. Lahko vsakih deset minut hodite do vrat in preverite (to je poizvedovanje — vaša aplikacija ponavljajoče kliče API in sprašuje »kaj je novega?«). Ali pa vam kurir pošlje sporočilo, ko jo dostavi (to je webhook).

Sporočilo je očitno boljše — če mu lahko zaupate. Če bi lahko kdorkoli poslal sporočilo »paket dostavljen«, bi želeli preveriti, ali je res prišlo od kurirja. In če je bil vaš telefon izklopljen, ko je sporočilo prišlo, bi želeli, da kurir poskusi znova pozneje. Ti dve skrbi — preverjanje in ponovni poskusi — sta večina tistega, kar naredi webhooke zahtevne.

Kako webhook deluje po korakih

1. Ustvarite končno točko v zaledju svoje aplikacije: naslov, na primer https://vasaaplikacija.si/webhooks/stripe, ki sprejema zahteve POST.
2. Ta naslov registrirate pri ponudniku in izberete dogodke, ki jih želite (na primer »zaključen nakup« in »preklicana naročnina«).
3. Ponudnik vam da podpisni ključ. Shranite ga kot skrivnost na svojem strežniku — glejte okoljske spremenljivke in skrivnosti.
4. Zgodi se dogodek. Ponudnik pošlje HTTP zahtevo na vaš naslov z JSON vsebino, ki opisuje dogodek, in z glavo podpisa.
5. Vaša aplikacija preveri podpis, zabeleži ID dogodka, hitro odgovori s kodo uspeha (200) in šele nato opravi delo.
6. Če vaša aplikacija ne odgovori z uspehom, mnogi ponudniki poskusijo znova pozneje.

Podpisi

Podpis dokaže, da zahteva prihaja od ponudnika in da ni bila spremenjena. Stripe na primer izračuna HMAC (vrsto ključnega prstnega odtisa) s SHA-256 nad vsebino zahteve in časovnim žigom z uporabo podpisnega ključa ter ga pošlje v glavi Stripe-Signature. Vaša aplikacija izvede isti izračun s svojo kopijo ključa; če se rezultata ujemata, je zahteva pristna. Ker je podpisan tudi časovni žig, lahko zavrnete stare zahteve, ki jih nekdo posname in predvaja pozneje — po Stripovi dokumentaciji iz septembra 2026 imajo njihove knjižnice privzeto petminutno tolerance.

Praktična podrobnost: podpis se izračuna nad surovo vsebino zahteve. Če vaše ogrodje JSON razčleni in preoblikuje, preden preverite, preverjanje ne uspe. To je zelo pogosta napaka.

Ponovni poskusi, podvajanja in vrstni red

Ponudniki se razlikujejo, zato preverite dokumentacijo vsakega. Stanje septembra 2026:

Stripova dokumentacija tudi pravi, da dogodki niso zagotovljeno dostavljeni v vrstnem redu, v katerem so se zgodili, in da lahko isti dogodek občasno pride več kot enkrat, zato priporoča sledenje ID-jem dogodkov.

Splošna lekcija velja za vsakega ponudnika: dogodki lahko pridejo pozno, večkrat in izven vrstnega reda. Vaša obdelava mora biti idempotentna — obdelava istega dogodka dvakrat ima enak učinek kot obdelava enkrat.

Delovni primer: odklep plačanega tečaja

Prodajate spletni tečaj. Študent klikne Kupi, plača na Stripovi gostujoči strani za nakup in je vrnjen na vaše spletno mesto.

Krhek način: stran »hvala« odklene tečaj. Če študent med preusmeritvijo zapre brskalnik, je plačal, a nima dostopa. Če nekdo ugane naslov strani »hvala«, dobi dostop brez plačila.

Način z webhookom:

1. Ko Stripe potrdi plačilo, pošlje dogodek checkout.session.completed na /webhooks/stripe.
2. Vaše zaledje preveri podpis s podpisnim ključem. Če ne uspe, odgovori z 400 in ne naredi ničesar.
3. Preveri, ali je ID tega dogodka že obdelan. Če je, odgovori z 200 in se ustavi.
4. Shrani ID dogodka, odgovori z 200 in nato študentu odobri dostop ter mu pošlje dobrodošlo e-pošto.
5. Stran »hvala« samo sporoči »Plačilo prejeto — vaš tečaj se bo kmalu pojavil« in preveri stanje dostopa študenta.

Pozneje, če se naročnina prekliče ali kartica ne uspe, drugi webhook dogodki aplikaciji sporočijo, naj dostop odstrani ali ustavi. Tako se izdelki z naročninami ohranjajo usklajeni z obračunavanjem — glejte kaj je SaaS in kako dodati plačila v svojo aplikacijo.

Ključni pojmi

• Končna točka (endpoint): naslov v vaši aplikaciji, ki sprejema webhooke.
• Dogodek / vsebina (payload): kaj se je zgodilo in podatki, ki to opisujejo (običajno JSON).
• Podpisni ključ: skupna skrivnost za preverjanje podpisov.
• Idempotentno: varno za izvedbo večkrat z istim rezultatom.
• Poizvedovanje (polling): ponavljajoče spraševanje API-ja po spremembah namesto čakanja na webhook.
• Tunel: orodje, ki prenosnemu računalniku med razvojem da začasen javni naslov, da lahko webhooki dosežejo njega.

Pogoste napake in zmote

• Nepreverjanje podpisov. Naslov končne točke ni skrivnost. Prav preverjanje naredi zahtevo zaupanja vredno.
• Počasno delo pred odgovorom. Pošiljanje e-pošt ali ustvarjanje PDF-jev pred odgovorom lahko povzroči časovne omejitve, te pa sprožijo ponovne poskuse, ki povzročijo podvajanja.
• Predpostavka, da pride natanko enkrat in v vrstnem redu. Beležite ID-je dogodkov in se ne zanašajte na vrstni red prihoda.
• Uporaba naslova za predogled. Webhooki potrebujejo stabilen, javen naslov. Zasebni predogledi in localhost niso dosegljivi z interneta; uporabite objavljen naslov (ali tunel med testiranjem).
• Mešanje testnih in živih skrivnosti. Ponudniki pogosto izdajo različne podpisne ključe za testni in živi način. Shranite oba in uporabite pravi.
• Slepo zaupanje podatkom v dogodku pri pomembnih odločitvah. Pri dejanjih z visokimi vložki je smiselno po prejetju dogodka pridobiti najnovejše stanje prek API-ja ponudnika.

Kaj zahtevati od svojega AI graditelja

Dodaj na strežniku končno točko POST /webhooks/stripe. Preveri Stripov podpis z uporabo surove vsebine zahteve in skrivnosti STRIPE_WEBHOOK_SECRET. Zavrni neveljavne podpise s kodo 400. Shrani vsak ID dogodka in preskoči dogodke, ki so že obdelani. Hitro odgovori 200, nato obdelaj checkout.session.completed tako, da označiš naročilo kot plačano in pošlješ račun. Zabeleži vrsto dogodka. Ne odobri dostopa na strani za uspeh po plačilu.

Nato preizkusite: pošljite testni dogodek iz nadzorne plošče ponudnika, pošljite istega še enkrat in pošljite zahtevo z napačnim podpisom. Spremeni se lahko le pri prvem.

Webhooki v Mythexu

Mythex ne vodi ločene storitve za webhooke; agenta prosite, naj v zaledje vaše aplikacije doda končno točko za webhook, ponudniku pa daste svoj objavljeni naslov, saj webhooki potrebujejo javen naslov. Podpisni ključ shranite med skrivnosti projekta, in če ga spremenite na živi aplikaciji, ponovno objavite. Recept v dokumentaciji o obdelavi webhookov vsebuje začetni poziv, predloge trgovin pa so dobro izhodišče za aplikacije, ki sprejemajo plačila.

Vprašanja