Što je webhook? Kako aplikacije međusobno obavještavaju

Webhook je automatska poruka koju jedna usluga šalje vašoj aplikaciji čim se nešto dogodi. Kad uspije plaćanje kupca, Stripe šalje webhook na adresu u vašoj aplikaciji s porukom „plaćanje uspjelo, evo detalja“, a vaša aplikacija reagira — označi narudžbu plaćenom, pošalje račun, otključa račun. Ukratko: API je kad vaša aplikacija postavi pitanje drugoj usluzi; webhook je kad druga usluga pozove vašu aplikaciju da joj nešto kaže.

Zašto je važno kad gradite s AI-jem

Čim vaša aplikacija prima plaćanja, prima obrasce od drugog alata ili se povezuje s uslugama poput GitHuba, Shopifyja ili kalendara, naići ćete na webhookove. Oni su obično ispravan način da saznate da se nešto dogodilo, ali upravo tu AI-izgrađene aplikacije najčešće griješe na suptilne načine:

• Krajnja točka prihvaća bilo koji zahtjev, pa netko može lažirati događaj „plaćanje uspjelo“.
• Aplikacija daje pristup na stranici za preusmjeravanje nakon plaćanja umjesto na webhooku, pa ljudi koji zatvore karticu prerano nikad ne dobiju ono što su platili, a oni koji pronađu URL uspjeha dobiju to besplatno.
• Isti događaj stigne dvaput, pa kupac dobije dvije narudžbe ili dva e-maila.

Kad znate kako webhookovi rade, možete od početka tražiti te zaštite.

Svakodnevna usporedba: SMS o dostavi

O dolasku paketa možete saznati na dva načina. Možete svakih deset minuta hodati do ulaznih vrata da provjerite (to je polling — vaša aplikacija stalno poziva API da pita „ima li što novo?“). Ili vam kurir može poslati poruku kad je dostavljeno (to je webhook).

Poruka je očito bolja — pod uvjetom da joj možete vjerovati. Ako bi svatko mogao poslati poruku „paket dostavljen“, htjeli biste nekako znati da je zaista došla od kurira. A ako je telefon bio isključen kad je poruka stigla, htjeli biste da kurir pokuša ponovno kasnije. Ta dva pitanja — provjera i ponovni pokušaji — čine većinu zahtjevnosti webhookova.

Kako webhook radi, korak po korak

1. Stvorite krajnju točku u pozadini vaše aplikacije: URL kao https://vasaapp.com/webhooks/stripe koji prihvaća POST zahtjeve.
2. Registrirajte taj URL kod pružatelja i odaberite koje događaje želite (na primjer „checkout završen“ i „pretplata otkazana“).
3. Pružatelj vam daje tajni ključ za potpisivanje. Spremite ga kao tajnu na poslužitelju — pogledajte varijable okruženja i tajne.
4. Dogodi se događaj. Pružatelj šalje HTTP zahtjev na vaš URL s JSON tijelom koje opisuje događaj i zaglavljem s potpisom.
5. Vaša aplikacija provjerava potpis, bilježi ID događaja, brzo odgovara statusnim kodom uspjeha (200) i tek onda obavlja posao.
6. Ako vaša aplikacija ne odgovori uspjehom, mnogi pružatelji pokušavaju ponovno kasnije.

Potpisi

Potpis dokazuje da zahtjev dolazi od pružatelja i da nije izmijenjen. Stripe, na primjer, računa HMAC (vrstu ključem zaštićenog otiska) s SHA-256 nad tijelom zahtjeva i vremenskom oznakom, koristeći tajni ključ za potpisivanje, i šalje ga u zaglavlju Stripe-Signature. Vaša aplikacija radi isti izračun sa svojom kopijom ključa; ako se rezultati podudaraju, zahtjev je autentičan. Budući da je i vremenska oznaka potpisana, možete odbiti stare zahtjeve koje je netko snimio i kasnije ponovno poslao — Stripeove biblioteke po defaultu koriste toleranciju od pet minuta, prema njihovoj dokumentaciji iz rujna 2026.

Jedan praktičan detalj: potpis se računa nad sirovim tijelom zahtjeva. Ako vaš okvir parsira i ponovno oblikuje JSON prije provjere, provjera ne prolazi. To je vrlo česta greška.

Ponovni pokušaji, duplikati i redoslijed

Pružatelji se razlikuju, zato provjerite dokumentaciju svakog. Od rujna 2026.:

Stripeova dokumentacija također kaže da događaji nisu zajamčeno stigli onim redom kojim su se dogodili te da isti događaj povremeno može stići više puta, pa preporučuje praćenje ID-jeva događaja.

Opća pouka vrijedi za svakog pružatelja: događaji mogu stići kasno, više puta i izvan redoslijeda. Vaša obrada treba biti idempotentna — obrada istog događaja dvaput ima isti učinak kao jednom.

Primjer: otključavanje plaćenog tečaja

Prodajete online tečaj. Student klikne Kupi, plati na Stripeovoj gotovoj stranici za plaćanje i bude vraćen na vašu stranicu.

Krhki način: stranica „hvala“ otključa tečaj. Ako student zatvori preglednik tijekom preusmjeravanja, platio je, ali nema pristup. Ako netko pogodi URL stranice „hvala“, dobiva pristup bez plaćanja.

Način s webhookom:

1. Kad Stripe potvrdi plaćanje, šalje događaj checkout.session.completed na /webhooks/stripe.
2. Vaša pozadina provjerava potpis tajnim ključem za potpisivanje. Ako ne prođe, odgovara 400 i ne radi ništa.
3. Provjerava je li taj ID događaja već obrađen. Ako jest, odgovara 200 i staje.
4. Sprema ID događaja, odgovara 200, zatim studentu daje pristup i šalje e-mail dobrodošlice.
5. Stranica „hvala“ samo kaže „Plaćanje primljeno — vaš tečaj će se uskoro pojaviti“ i provjerava status pristupa studenta.

Kasnije, ako se pretplata otkaže ili kartica odbije, drugi webhook događaji govore vašoj aplikaciji da ukloni ili obustavi pristup. Tako pretplatnički proizvodi ostaju sinkronizirani s naplatom — pogledajte što je SaaS i kako dodati plaćanja u aplikaciju.

Ključni pojmovi

• Krajnja točka: URL u vašoj aplikaciji koji prima webhookove.
• Događaj / payload: što se dogodilo i podaci koji to opisuju (obično JSON).
• Tajni ključ za potpisivanje: zajednički tajni ključ za provjeru potpisa.
• Idempotentno: sigurno za pokretanje više puta uz isti rezultat.
• Polling: ponovno i ponovno pitanje API-ja ima li promjena, umjesto čekanja na webhook.
• Tunel: alat koji laptopu daje privremenu javnu adresu kako bi webhookovi mogli doći do njega tijekom razvoja.

Česte pogreške i zablude

• Neprovjeravanje potpisa. URL krajnje točke nije tajna. Provjera je ono što zahtjev čini pouzdanim.
• Sporo odrađivanje posla prije odgovora. Slanje e-mailova ili generiranje PDF-ova prije odgovora može uzrokovati isteke vremena, što pokreće ponovne pokušaje, što uzrokuje duplikate.
• Pretpostavka „točno jednom, redom“. Bilježite ID-jeve događaja i ne oslanjajte se na redoslijed dolaska.
• Korištenje URL-a pregleda. Webhookovima treba stabilna, javna adresa. Privatni pregledi i localhost nisu dostupni s interneta; koristite objavljeni URL (ili tunel tijekom testiranja).
• Miješanje testnih i živih tajni. Pružatelji često izdaju različite tajne za potpisivanje u testnom i živom načinu. Spremite obje i koristite pravu.
• Slijepo vjerovanje sadržaju za važne odluke. Za radnje s visokim ulogom razumno je nakon primitka događaja dohvatiti najnovije stanje iz API-ja pružatelja.

Što tražiti od vašeg AI graditelja

Dodaj na poslužitelju krajnju točku POST /webhooks/stripe. Provjeri Stripe potpis koristeći sirovo tijelo zahtjeva i tajnu STRIPE_WEBHOOK_SECRET. Odbij neispravne potpise s 400. Spremaj svaki ID događaja i preskači događaje koji su već obrađeni. Brzo odgovori 200, zatim obradi checkout.session.completed tako da narudžbu označiš plaćenom i pošalješ račun. Zabilježi vrstu događaja. Ne odobravaj pristup sa stranice uspjeha nakon plaćanja.

Zatim testirajte: pošaljite testni događaj iz nadzorne ploče pružatelja, pošaljite isti ponovno i pošaljite zahtjev s pogrešnim potpisom. Samo prvi bi smio nešto promijeniti.

Webhookovi u Mythexu

Mythex nema zasebnu uslugu webhookova; zamolite agenta da doda krajnju točku webhooka u pozadinu vaše aplikacije, a pružatelja usmjerite na svoj objavljeni URL, jer webhookovi trebaju javnu adresu. Tajna za potpisivanje ide u tajne vašeg projekta, a ako je promijenite na živoj aplikaciji, ponovno objavite. Recept u dokumentaciji za obradu webhookova ima početni prompt, a predlošci trgovina dobro su polazište za aplikacije koje primaju plaćanja.

Pitanja