Payment webhook je serverska poruka kojom payment gateway ili drugi učesnik u naplati obaveštava vaš sistem da se dogodio događaj: pokušaj plaćanja je uspeo, zahteva dodatnu autentifikaciju, odbijen je, refundiran ili osporen. Za razliku od odgovora koji korisnik dobije odmah posle klika na dugme „Plati“, webhook stiže asinhrono — često kasnije, nezavisno od toga da li je kupac zatvorio stranicu.
Pouzdan pristup zato ne tretira webhook kao običan HTTP poziv koji samo treba proslediti dalje. Potrebno je proveriti da je poruka zaista došla od očekivanog provajdera, sačuvati je, bezbedno je obraditi, tolerisati ponovljenu dostavu i predvideti situacije u kojima događaji stignu van redosleda ili uopšte ne stignu. U nastavku je praktičan model za projektovanje tog toka, bez vezivanja za jednu konkretnu platformu.
Zašto je asinhroni status važan
Korisnički interfejs i serverski sistem ne dobijaju nužno istu informaciju u istom trenutku. Preusmeravanje na stranicu za uspeh može značiti da je iniciran payment flow, ali ne mora biti dovoljan dokaz da je uplata konačno potvrđena. S druge strane, webhook može stići nakon što je korisnik napustio checkout, a upravo on može sadržati informaciju potrebnu za izdavanje računa, rezervaciju proizvoda ili slanje digitalne usluge.
Razlog je i u tome što plaćanje može imati više koraka: autentifikaciju korisnika, komunikaciju sa bankom izdavaocem kartice, obradu kod procesora, refundaciju ili naknadni dispute. Svaki korak može proizvesti novi događaj. Zbog toga se poslovna odluka — na primer, da se porudžbina označi kao plaćena — donosi na osnovu verifikovanog serverskog događaja i pravila vašeg sistema, a ne samo na osnovu URL-a na koji se kupac vratio.
Osnovni tok pouzdane obrade
Najjednostavnija korisna podela je na četiri faze:
- Prijem: endpoint prima HTTP zahtev i čuva sirovu poruku ili njen bezbedan zapis.
- Autentičnost: proverava se potpis, tajna ili drugi mehanizam koji propisuje payment provajder.
- Trijaža i obrada: događaj se povezuje sa internim nalogom ili payment pokušajem, a poslovna logika se izvršava najviše jednom po relevantnom događaju.
- Usklađivanje: sistem beleži ishod, prati neuspehe i po potrebi proverava stanje direktnim pozivom provajderu ili kroz periodični reconciliation proces.
Ove faze ne moraju biti četiri fizička servisa. Za manju aplikaciju mogu biti moduli jedne backend aplikacije. Bitno je da granice postoje u modelu podataka i u odgovornosti komponenti. Prijem poruke ne bi trebalo da zavisi od toga da li je slanje e-maila, kreiranje fakture ili ažuriranje zaliha upravo uspelo.
1. Endpoint treba da bude mali i predvidiv
Webhook endpoint treba da prihvata samo očekivani HTTP metod, da bude dostupan preko HTTPS-a i da što brže potvrdi prijem nakon osnovnih provera. Teže operacije, kao što su slanje obaveštenja kupcu, obračun provizije ili poziv drugom internom servisu, bolje je staviti u red za obradu ili u zaseban background posao.
Brz odgovor nije isto što i slepo vraćanje statusa 200. Ako poruka nije autentična ili je telo neispravno, endpoint treba da postupi u skladu sa dokumentacijom provajdera i internom politikom. Ako je događaj legitimno primljen, ali obrada privremeno nije moguća, sistem mora imati jasan plan: ponovni pokušaj, dead-letter red ili ručnu intervenciju. Ti scenariji se ne rešavaju tako što se greška sakrije.
2. Sačuvajte događaj pre poslovne obrade
Minimalni zapis obično sadrži identifikator događaja, tip događaja, identifikator objekta plaćanja, vreme prijema, rezultat verifikacije, broj pokušaja obrade i trenutni status obrade. Po potrebi se čuvaju i zaglavlja i telo poruke, uz ograničenje pristupa i politiku zadržavanja.
Ovaj zapis pomaže kada kupac tvrdi da je platio, kada se refundacija ne vidi u aplikaciji ili kada morate da utvrdite zašto je porudžbina promenila stanje. Ne treba automatski čuvati osetljive podatke koji nisu potrebni za poslovnu funkciju. Broj kartice i slični podaci ne pripadaju proizvoljnom webhook logu; način čuvanja payment metode treba razmatrati odvojeno, na primer kroz tokenizaciju kartica bez čuvanja broja kartice.
Verifikacija: potpis, telo poruke i tajne
Webhook potpis se najčešće računa nad tačnim, neizmenjenim telom zahteva i tajnim ključem koji dele provajder i vaš server. Zato je važno sačuvati raw body pre nego što framework parsira JSON, promeni razmake ili normalizuje redosled polja. Provera nad ponovo serijalizovanim JSON-om može biti neispravna iako sadržaj izgleda identično.
Praktična pravila su:
- tajnu držati u secret manageru ili zaštićenoj konfiguraciji, nikada u repozitorijumu;
- koristiti verifikacionu biblioteku i postupak koji propisuje konkretni provajder;
- proveriti vremenski prozor ako potpis uključuje timestamp, čime se smanjuje rizik ponovne reprodukcije stare poruke;
- ne logovati punu tajnu ni osetljive delove poruke;
- rotirati tajne prema proceduri provajdera i omogućiti kontrolisani prelaz na novu tajnu;
- odvojiti testne i produkcione endpoint-e, ključeve i podatke.
IP allowlist može biti dodatna kontrola, ali nije zamena za kriptografsku verifikaciju. IP adrese se mogu promeniti, a infrastruktura provajdera može koristiti više opsega. Uvek treba pratiti aktuelnu dokumentaciju izabranog payment sistema.
Idempotency: isti događaj ne sme dvaput proizvesti isti efekat
Provajderi ponavljaju dostavu kada ne dobiju očekivanu potvrdu ili kada privremeno ne mogu da utvrde da je poruka uspešno primljena. Zato isti webhook može stići više puta. To nije izuzetak koji se rešava ručnim proveravanjem; to je normalna osobina distribuiranog sistema.
Najčešće rešenje je jedinstvena evidencija obrađenih događaja. Pre izvršavanja poslovne akcije sistem proverava da li je identifikator događaja već uspešno obrađen. Ograničenje jedinstvenosti u bazi mora biti atomsko, jer dve paralelne dostave mogu proći kroz običnu proveru „da li postoji“ u istom trenutku.
Važno je razlikovati idempotentnost webhook handlera od idempotentnosti API poziva kojim ste, na primer, kreirali payment intent ili poslali refundaciju. Za širi model sprečavanja duple naplate pogledajte vodič Idempotency u plaćanjima: kako sprečiti duplu naplatu. Kod webhook-a se dodatno mora razmotriti i šta se dešava ako se zapis događaja sačuva, a kasnija poslovna akcija padne.
Šta ako obrada pukne na pola?
Na primer, sistem primi potvrdu uspešnog plaćanja, označi porudžbinu kao plaćenu, a zatim zbog greške ne rezerviše zalihu. Ponovljeni webhook ne sme ponovo da naplati kupca niti da napravi duplu porudžbinu, ali mora da omogući nastavak ili popravku neuspešne poslovne akcije.
Zato je korisno imati odvojene statuse: received, verified, processing, processed i failed, uz broj pokušaja i poslednju grešku. Transakcija baze može atomski upisati događaj i promenu lokalnog payment zapisa, dok se sporedne aktivnosti obrađuju kroz pouzdan red. Ako je potrebna jaka garancija između upisa u bazu i slanja posla, outbox obrazac može smanjiti rizik da jedan korak uspe, a drugi se izgubi.
Redosled događaja nije garantovan
U distribuiranim sistemima događaji mogu stići van redosleda. Na primer, obaveštenje o neuspešnom pokušaju može stići posle događaja koji je otvorio novi pokušaj, ili refundacija može biti obrađena pre nego što je lokalni sistem dobio sve prethodne informacije. Ne treba pretpostaviti da je poslednji primljeni webhook automatski najnovije stanje.
Svaki lokalni payment zapis treba povezati sa stabilnim identifikatorom objekta kod provajdera i, kada je dostupno, sa vremenom događaja, verzijom ili drugim podatkom koji dokumentacija definiše. Handler treba da ima dozvoljene prelaze, a ne samo uslov tipa „postavi status na vrednost iz poslednje poruke“. Na primer, već refundirano plaćanje ne bi trebalo vratiti u paid samo zato što je zakašnjeli događaj pogrešnim redom stigao do aplikacije.
Za modeliranje tih prelaza koristan je zaseban vodič Payment state machine: pending, paid, failed, refunded i disputed. On pomaže da se razdvoje status payment objekta, status porudžbine i status isporuke — tri stvari koje nisu nužno isto.
Veza između webhook događaja i vaše porudžbine
Webhook obično nosi identifikator payment objekta, ali vaš sistem mora znati kojoj korpi, porudžbini ili korisniku taj objekat pripada. Tu vezu je najbolje uspostaviti već pri kreiranju payment pokušaja, preko internog order ID-a ili metadata polja koja payment platforma podržava.
Ne treba verovati vrednostima koje stižu iz browsera kao jedinom izvoru za cenu, valutu ili identitet porudžbine. Pri prijemu događaja sistem treba da pronađe postojeći interni zapis, proveri da li se valuta i iznos uklapaju u očekivani payment pokušaj i odbije ili izdvoji nelogične kombinacije za istragu. Posebno proverite scenario u kojem je isti payment identifikator neočekivano povezan sa više naloga ili porudžbina.
Za proizvode ili usluge koje se isporučuju tek nakon plaćanja, isporuka treba da zavisi od verifikovanog i dozvoljenog prelaza lokalnog statusa, ne od same posete success stranici. Slično važi za izdavanje računa, aktivaciju članstva i promenu pristupnih prava.
Retry, dead-letter i ručna intervencija
Privremena greška nije isto što i trajno nevažeća poruka. Pad baze, timeout internog servisa ili kratkotrajna nedostupnost provajdera mogu se rešiti ponovnim pokušajem. Neispravan potpis, nepoznat format ili događaj koji se ne može povezati sa porudžbinom zahtevaju drugačiji tretman.
Definišite:
- koje greške se automatski ponavljaju;
- koliko dugo pokušaji traju i da li koriste rastući razmak između pokušaja;
- kada se događaj premešta u dead-letter red;
- ko dobija upozorenje i koji podaci su potrebni za bezbednu istragu;
- kako se događaj može ponovo obraditi bez ručnog menjanja istorijskih zapisa.
Ručna obrada ne bi trebalo da znači direktno menjanje statusa u bazi bez traga. Bolje je imati administratorsku akciju koja beleži ko je, kada i zašto pokrenuo ponovnu obradu, uz ista pravila idempotentnosti kao kod automatskog toka.
Monitoring koji pokazuje stvarni problem
Sam broj HTTP 200 odgovora nije dovoljan. Pratite broj primljenih događaja po tipu, procenat neuspešnih verifikacija, kašnjenje od prijema do obrade, broj ponovljenih pokušaja, starost najstarijeg događaja u redu i broj događaja koji čekaju ručnu intervenciju.
Logovi treba da koriste korelacioni ID i payment identifikator, ali da ne otkrivaju tajne ili nepotrebne kartične podatke. Alarm može biti koristan kada se nagomila red za obradu, kada se pojavi neuobičajen broj nepoznatih događaja ili kada postoji razlika između lokalnih uspešnih uplata i izveštaja payment provajdera.
Reconciliation nije znak da webhook arhitektura ne radi. On je zaštitna mreža za slučajeve mrežnog prekida, pogrešne konfiguracije endpoint-a, promene pretplate na tipove događaja ili greške u sopstvenoj obradi. Periodično poređenje treba da bude kontrolisano, ograničeno i idempotentno, sa jasnim pravilima šta se automatski ispravlja, a šta ide na proveru.
Testiranje pre produkcije
Testirajte više od uspešnog plaćanja. Minimalni scenario-set uključuje:
- validan događaj sa ispravnim potpisom;
- isti događaj dostavljen više puta paralelno;
- izmenjeno telo poruke ili nevažeći potpis;
- duži period obrade i timeout;
- događaje van redosleda;
- nepoznat tip događaja koji je legitimno potpisan;
- refundaciju, neuspeh, dispute i ponovno plaćanje kada ih vaš model podržava;
- grešku posle upisa u bazu, ali pre slanja background posla;
- ponovnu obradu iz dead-letter reda;
- reconciliation koji pronalazi razliku između lokalnog i udaljenog stanja.
Koristite sandbox ili test režim provajdera, ali proverite i razlike u odnosu na produkciju: endpoint URL, tajne, dozvoljene događaje, timeoute, redosled migracija i monitoring. Pre puštanja napravite runbook: gde se vidi događaj, kako se razlikuje odbijena poruka od privremenog pada i ko odobrava korekciju porudžbine.
Kako se webhook uklapa u kompletnu integraciju
Webhook je samo jedan deo payment integracije. Potrebni su i izbor payment flow-a, mapiranje statusa, obrada grešaka, zaštita podataka, testiranje, refundacije i usklađivanje sa poslovnim pravilima. Ako tek projektujete ceo tok, pogledajte stranicu integracija platnih kartica kao širi kontekst, a ovaj članak koristite za serverski deo asinhronih obaveštenja.
Kada se payment tok ugrađuje u novu prodavnicu, rezervacioni sistem ili custom aplikaciju, webhook ugovor treba definisati zajedno sa modelom porudžbine i ostatkom backend arhitekture. Zato je relevantna i izrada sajta kada ona uključuje povezivanje checkout-a, administracije, kataloga i isporuke, ali sama webhook obrada ne treba da bude dodata tek na kraju kao izolovani endpoint.
Pre implementacije napišite kratku specifikaciju: koje događaje slušate, koji su dozvoljeni prelazi, koji identifikator povezuje payment i porudžbinu, šta se radi kod duplikata, koliko se čuvaju zapisi i ko rešava neuspele obrade. Takav dokument često otkrije nejasnoće pre nego što se pojave u stvarnoj naplati.
Kontrolna lista za pouzdan payment webhook
- Endpoint koristi HTTPS i odvojenu konfiguraciju za test i produkciju.
- Raw body se čuva dovoljno rano da bi verifikacija potpisa bila moguća.
- Tajna nije u kodu ni u logovima.
- Identifikator događaja ima jedinstvenu zaštitu u bazi.
- Handler ne zavisi od redosleda dostave bez provere dozvoljenih prelaza.
- Payment događaj je povezan sa internim payment pokušajem i porudžbinom.
- Sporedne akcije imaju retry, outbox ili drugi pouzdan mehanizam.
- Postoji dead-letter tok i procedura za ručnu istragu.
- Monitoring meri kašnjenje, neuspehe i backlog, ne samo HTTP status.
- Periodični reconciliation može otkriti izgubljene ili pogrešno obrađene događaje.
- Testovi pokrivaju duplikate, nevažeći potpis, kašnjenje, redosled i parcijalni neuspeh.
Najvažnija odluka je da asinhroni događaj tretirate kao pouzdanu poruku koju treba potvrditi, sačuvati i obraditi po pravilima — ne kao običan callback koji menja jedan status. Kada su verifikacija, idempotentnost, state machine i reconciliation projektovani zajedno, payment tok je otporniji na mrežne probleme i realne varijacije u ponašanju korisnika i provajdera.
