Šta treba da vrati krajnja tačka webhook-a za praćenje? Statusni kodovi, vremenska ograničenja i ponovni pokušaji?
Webhook krajnja tačka za praćenje treba da vrati brz, nameran 2xx odgovor nakon što prihvati događaj na obradu. U većini integracija, najbezbedniji obrazac je autentifikovati zahtev, proveriti sadržaj, sačuvati ili staviti događaj u red čekanja i potvrditi ga odgovorom 200 OK ili 202 Accepted. Koristite 4xx odgovore za zahteve koje pošiljalac ne treba ponovo da šalje, a 5xx odgovore kada je privremeni problem na strani servera sprečio prihvatanje. Tačno ponašanje u vezi sa istekom vremena i ponovnim pokušajima i dalje zavisi od ugovora provajdera webhooka, zato implementaciju treba zasnovati na dokumentovanom ponašanju pošiljaoca, a ne na pretpostavkama.
Za webhook za praćenje ili status pošiljke, ova razlika je važna zato što događaji isporuke mogu stići više puta, van redosleda ili biti ponovo reprodukovani nakon mrežnog kvara. Zadatak krajnje tačke nije nužno da završi svaku poslovnu operaciju pre odgovora. Njen prvi zadatak je da pouzdano odluči da li je događaj prihvaćen.
Ugovor o odgovoru u praksi
Webhook odgovor ima dve ciljne publike: sistem koji šalje zahtev i vašu aplikaciju. Pošiljaocu je potreban jasan HTTP rezultat kako bi odlučio da li da isporuku označi kao uspešnu, ponovi je ili zaustavi. Vašoj aplikaciji je potrebno dovoljno vremena da proveri i trajno zabeleži događaj. Ovi ciljevi se lakše ostvaruju kada krajnja tačka ima mali sinhroni put i odvojeni asinhroni put obrade.
- Primite HTTP zahtev preko HTTPS-a.
- Proverite potpis, akreditive za autentifikaciju, vremensku oznaku ili druge kontrole integriteta zahteva koje provajder zahteva.
- Raščlanite i proverite sadržaj bez izvršavanja sporih naknadnih operacija.
- Upišite događaj ili zapis za sprečavanje duplikata i referencu na događaj u trajno skladište ili pouzdan red čekanja.
- Vratite nameran 2xx odgovor.
- Obradite ažuriranje praćenja, obaveštenje kupca, promenu zaliha ili drugu poslovnu radnju asinhrono.
Odgovor ne treba da tvrdi da je događaj prihvaćen ako postoji samo u memoriji procesa. Ako se aplikacija odmah sruši nakon vraćanja uspeha, događaj koji nikada nije sačuvan može biti izgubljen, dok pošiljalac veruje da je isporuka uspela. Zato trenutak vraćanja 2xx odgovora treba da odgovara vašoj stvarnoj garanciji trajnosti.
Koji statusni kod treba da vrati webhook?
| Odgovor | Značenje za pošiljaoca | Uobičajena upotreba webhooka |
|---|---|---|
200 OK | Zahtev je prihvaćen i uspešno obrađen. | Praktična podrazumevana opcija nakon provere i trajnog prihvatanja. |
202 Accepted | Zahtev je prihvaćen za obradu, ali rad se može nastaviti. | Korisno kada je događaj bezbedno stavljen u red čekanja, ali se poslovna obrada izvršava asinhrono. |
204 No Content | Zahtev je uspešan i telo odgovora nije potrebno. | Pogodno kada provajder prihvata prazan uspešan odgovor. |
400–499 | Zahtev je nevažeći, neovlašćen ili neprihvatljiv u poslatom obliku. | Neispravan sadržaj, neuspešna autentifikacija, nevažeći potpis ili trajno odbijen događaj. |
429 Too Many Requests | Primalac primenjuje ograničenje brzine zahteva. | Koristite samo kada su ponašanje pošiljaoca pri ponovnom pokušaju i vaša politika ograničenja brzine usklađeni. |
500–599 | Primalac nije mogao da prihvati zahtev zbog problema na strani servera ili privremenog problema. | Nedostupnost baze podataka, kvar reda čekanja, kvar zavisnosti ili neočekivana greška aplikacije. |
200 OK je često najmanje iznenađujući izbor jer se široko razume kao uspešan prijem. 202 Accepted je takođe semantički koristan kada je krajnja tačka prihvatila događaj za kasniju obradu. Nijedan kod nije automatski ispravan: dokumentacija pošiljaoca može definisati koji 2xx odgovori se računaju kao uspešni, a neki provajderi mogu očekivati određeno telo ili tip sadržaja.
Nemojte vraćati 2xx odgovor samo zato što je HTTP zahtev stigao do vašeg servera. Ako provera potpisa ne uspe ili se sadržaj ne može bezbedno protumačiti, 4xx odgovor je obično istinitiji. Suprotno tome, nemojte vraćati 4xx zbog privremenog pada baze podataka ako bi događaj kasnije mogao da uspe. 5xx odgovor pošiljaocu koji podržava ponovne pokušaje daje priliku da ponovo isporuči događaj, iako provajder može primeniti sopstvenu politiku.
Kako treba obrađivati istek vremena?
Vrednosti isteka vremena za webhook zavise od provajdera. Ne postoji univerzalno HTTP vremensko ograničenje koje koristi svaka platforma za praćenje, a pošiljalac može prestati da čeka pre nego što vaša aplikacija završi sporu operaciju. Dokumentovani istek vremena pošiljaoca tretirajte kao krajnju granicu, a ne kao cilj. Vaša krajnja tačka obično treba da odgovori znatno pre te granice.
Najčešća greška u dizajnu je obavljanje celokupnog naknadnog rada pre potvrde webhooka. Rukovalac može redom pozvati bazu podataka, sistem za upravljanje porudžbinama, servis za obaveštenja i analitički sistem. Jedna spora zavisnost može dovesti do toga da pošiljalac vidi istek vremena, iako vaša aplikacija na kraju završi rad. Pošiljalac tada može ponoviti zahtev, stvarajući duplikate obrade ili konkurentna ažuriranja.
Sinhroni put ograničite na rad potreban za bezbednu odluku o prihvatanju. To obično obuhvata autentifikaciju zahteva, osnovnu proveru šeme, trajno čuvanje događaja i objavljivanje u redu čekanja. Skupo obogaćivanje podataka, provere kod prevoznika, slanje poruka kupcima i pozive API-jima trećih strana prepustite radniku. Odvojeno pratite vreme prijema, provere, čuvanja i potvrde događaja od vremena njegove obrade.
Istek vremena nije isto što i neuspešna poslovna operacija. Iz perspektive pošiljaoca, istek vremena obično znači da nije primio upotrebljiv uspešan odgovor. Vaša usluga je možda uspešno sačuvala događaj neposredno pre prekida veze. Zato su idempotentnost i sprečavanje duplikata neophodni čak i kada krajnja tačka deluje pouzdano.
Šta uzrokuje ponovne pokušaje?
Pošiljalac webhooka može ponoviti zahtev nakon greške veze, isteka vremena ili odgovora koji njegov ugovor klasifikuje kao neuspešan. Tačan raspored, maksimalan broj pokušaja, algoritam čekanja i period isporuke razlikuju se među provajderima. Nemojte obećavati fiksan broj ponovnih pokušaja osim ako je naveden u dokumentaciji provajdera.
Primalac treba da pretpostavi da se ponovni pokušaji mogu dogoditi i da ih namerno uzme u obzir pri dizajnu:
- Koristite identifikator događaja kada je dostupan. Sačuvajte ga uz jedinstveno ograničenje ili ekvivalentan ključ za sprečavanje duplikata.
- Obradu učinite idempotentnom. Dvostruka primena istog ažuriranja statusa isporuke ne treba da pošalje dve poruke kupcu, kreira dva povraćaja novca ili nepravilno pomeri porudžbinu.
- Sačuvajte originalni sadržaj ili koristan zapis revizije. To podržava ponovnu reprodukciju, istragu i usaglašavanje.
- Odvojite prihvatanje od obrade. Radnik može ponoviti interne neuspehe bez prisiljavanja pošiljaoca da ponovi čitavu HTTP razmenu.
- Beležite kodove odgovora i kašnjenje. Porast 5xx odgovora, istekâ vremena ili duplih ID-jeva događaja može otkriti prekid rada pre nego što korisnici prijave nedostajuća ažuriranja praćenja.
Duplirani događaj obično treba da dobije uspešan odgovor ako je originalni događaj već trajno prihvaćen. Vraćanje greške za svaki duplikat može pokrenuti nepotrebne ponovne pokušaje. Krajnja tačka može zabeležiti da je događaj ranije viđen, preskočiti ponovljenu poslovnu radnju i vratiti istu klasu uspeha koja se koristi za novoprihvaćeni događaj.
Kada treba vratiti 4xx, 429 ili 5xx?
Vratite 4xx kada ponavljanje istog zahteva verovatno neće rešiti problem. Primeri uključuju nevažeći potpis, nedostajuću obaveznu autentifikaciju, nepodržan oblik sadržaja ili zahtev koji krši trajno pravilo provere. Pre izbora 4xx proverite da li pošiljalac taj status tretira kao trajni neuspeh. Neke platforme imaju sopstvena pravila za neuspele isporuke.
429 koristite pažljivo. HTTP definiše 429 za ograničenje brzine, a zaglavlje Retry-After može saopštiti kada bi ponovni pokušaj mogao biti odgovarajući. Međutim, ne tumače svi pošiljaoci webhooka 429 na isti način. Ako je vaš red čekanja pun ili je usluga preopterećena, potvrdite da će provajder bezbedno ponoviti zahtev i da njegov raspored pokušaja neće pogoršati preopterećenje. Ograničen ulazni red čekanja i plan povratnog pritiska obično su bolji od dopuštanja da zahtevi nepredvidivo ne uspeju.
Vratite 5xx kada primalac zbog privremenog problema ne može bezbedno da prihvati događaj. To obuhvata nedostupnu bazu podataka, neuspešan upis u trajni red čekanja ili internu grešku koja je sprečila proveru ili čuvanje. Vraćanje 200 uz tiho odbacivanje događaja otežava oporavak jer pošiljalac nema razlog da ponovo pokuša.
Izbegavajte oslanjanje na preusmeravanja kao što su 301, 302 ili 307 za isporuku webhooka. Obrada preusmeravanja razlikuje se među klijentima, a preusmeravanje potpisanog zahteva može uneti nejasnoće u vezi sa odredištem, metodom i telom. Umesto toga, podesite provajdera sa konačnom HTTPS krajnjom tačkom.
Pouzdana politika odgovora za događaje praćenja
Za većinu integracija webhooka za praćenje, sledeća politika je razumna početna tačka:
- Vratite
200ili202nakon što događaj prođe autentifikaciju i bude trajno sačuvan ili stavljen u pouzdan red čekanja. - Vratite 4xx odgovor za nevažeći potpis, nevažeću autentifikaciju ili trajno neupotrebljiv sadržaj, u skladu sa dokumentovanim pravilima provajdera.
- Vratite 5xx kada privremeni kvar sprečava trajno prihvatanje.
- Vratite uspešan odgovor za bezbedno prepoznat duplikat, uz sprečavanje duplih poslovnih efekata.
- Rukovalac treba da bude brz i merite kašnjenje potvrde.
- Testirajte scenarije isteka vremena, ponovnog pokušaja, duplikata, pogrešnog redosleda, neispravnog sadržaja i pada provajdera pre puštanja u produkciju.
Ako integrišete API za praćenje, počnite od dokumentacije provajdera za webhook i potvrdite prihvaćene kodove uspeha, metod potpisivanja zahteva, istek vremena, okidače za ponovni pokušaj, šemu sadržaja i identifikator događaja. Za 17TRACK integracije, zvanična dokumentacija Tracking API-ja je odgovarajuće mesto za proveru ugovora specifičnog za provajdera, umesto zaključivanja na osnovu opšte HTTP prakse.
Kontrolna lista za implementaciju
- Krajnja tačka je dostupna preko HTTPS-a i ima stabilan produkcijski URL.
- Autentifikacija i provera potpisa obavljaju se pre poslovne obrade.
- Sirovi zahtev ili proverljiva reprezentacija čuva se gde je potrebno za proveru potpisa i rešavanje problema.
- Događaj se trajno čuva pre slanja uspešnog odgovora.
- Duplirane isporuke su bezbedne i ne ponavljaju nepovratne radnje.
- Radnici mogu ponoviti internu obradu nezavisno od HTTP ciklusa ponovnog pokušaja pošiljaoca.
- Evidencije sadrže ID događaja, vreme isporuke, kod odgovora, stanje obrade i ID korelacije bez izlaganja tajni.
- Upozorenja razlikuju isteke vremena krajnje tačke, 4xx greške provere, 5xx prekide rada, kašnjenja reda čekanja i duplirane isporuke.
- Dokumentovano ponašanje provajdera testirano je stvarnim događajima ili događajima u sandbox okruženju.
Često postavljana pitanja
Da li je 200 OK bolji od 202 Accepted za webhook?
Nijedan nije univerzalno bolji. Koristite 200 OK kada je zahtev prihvaćen i vaša integracija odgovor tretira kao opšti uspeh. Koristite 202 Accepted kada je događaj prihvaćen za asinhronu obradu. Potvrdite da pošiljalac izabrani 2xx odgovor klasifikuje kao uspešan.
Da li webhook krajnja tačka treba da čeka dok se ažuriranje praćenja potpuno ne obradi?
Obično ne. Treba da čeka samo dok događaj ne bude autentifikovan, proveren i trajno prihvaćen. Dugotrajni rad obično treba da se obavlja nakon potvrde kako spora zavisnost ne bi izazvala nepotreban istek vremena i ponovni pokušaj.
Šta treba da se dogodi kada isti događaj praćenja stigne dva puta?
Prepoznajte ga pomoću ID-ja događaja provajdera ili pažljivo dizajniranog ekvivalentnog ključa, preskočite duple sporedne efekte i vratite uspešan odgovor ako je događaj već prihvaćen. Tako ponovni pokušaji ostaju bezbedni bez skrivanja novih grešaka u obradi.
Da li nevažeći potpis treba da vrati 400 ili 401?
Izbor zavisi od vašeg modela autentifikacije i dokumentovanih očekivanja provajdera. Oba mogu saopštiti odbijanje, ali je doslednost važnija od univerzalnog izbora jednog koda. Nemojte potvrditi događaj čiju autentičnost ne možete da proverite.
Da li 5xx odgovor uvek izaziva ponovni pokušaj?
Ne. Mnogi webhook sistemi ponavljaju zahteve nakon isteka vremena i grešaka servera, ali okidači i rasporedi ponovnih pokušaja zavise od provajdera. Ponovne pokušaje tretirajte kao dokumentovano ponašanje integracije i proverite ih u testnom okruženju.
Izvori
- RFC 9110: HTTP Semantics — definicije uspešnih odgovora, grešaka klijenta, grešaka servera, preusmeravanja i obrade odgovora.
- RFC 6585: Additional HTTP Status Codes — specifikacija za
429 Too Many Requests. - Stripe Webhooks Documentation — praktične smernice za odgovore webhooka, asinhronu obradu i rukovanje dupliranim događajima.
- GitHub Docs: Handling Webhook Deliveries — pregled isporuka i operativna razmatranja za integracije webhooka.
- 17TRACK Tracking API Documentation — dokumentacija specifična za provajdera koju treba proveriti pri implementaciji integracija Tracking API-ja.


