(Isporuka webhookova · Nautilus)
Vaš proizvod objavljuje događaj jednim API pozivom. Nautilus ga stavlja u red, potpisuje i isporučuje svakom endpointu pretplaćenom na taj tip događaja. Neuspela isporuka se ponavlja po fiksnom rasporedu, a svaki pokušaj se pojavljuje u vašoj kontrolnoj tabli sa odgovorom koji je dobio.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer vrn_relay_•••" \
-d '{"event_type":"user.created","payload":{"id":"usr_123"}}'(Napraviti ili kupiti)
Prva verzija je POST zahtev u petlji ponovnih pokušaja. Prestaje da bude jednostavno kada server klijenta bude van funkcije ceo vikend, kada deployment handlera ode pokvaren pa treba ponovo poslati sat vremena događaja, i kada spor endpoint počne da zadržava sve ostale.
Napraviti sami
Isporuka webhookova u Nautilusu
(Ključne funkcionalnosti)
(01)
Odgovor različit od 2xx, ili timeout, računa se kao neuspeo pokušaj. Poruka se ponavlja sa rastućim razmacima: 8 pokušaja u oko 28 sati, isti raspored za svaki endpoint. Isporuka je at-least-once, pa ponovni pokušaj može da stigne do servera vašeg klijenta više puta.
(02)
Svaka poruka je potpisana HMAC SHA-256, sa tajnom koja pripada jednom endpointu. Svaka isporuka nosi tri zaglavlja (svix-id, svix-timestamp i svix-signature), a potpis pokriva id, vremensku oznaku i telo, pa vaši klijenti mogu da provere ko ga je poslao i odbiju ponovljen zahtev.
(03)
Objavljivanje događaja vraća 202 čim je poruka u redu. Isporuka na servere vaših klijenata dešava se posle, pa spor ili mrtav endpoint ne usporava zahtev koji vaš kod čeka.
(04)
Objavite jedan događaj, na primer user.created, i on se isporučuje svakom endpointu pretplaćenom na taj tip događaja. Dodajte poruci kanal da biste stigli samo do endpointa koji ga slušaju.
(05)
Svaki pokušaj se beleži sa vremenom, kodom odgovora i telom odgovora koji je vratio vaš server, da biste videli zašto je isporuka pala. Na kartici Events u kontrolnoj tabli možete ponovo poslati jednu isporuku, ili ponoviti sve što je palo od trenutka koji izaberete, do 14 dana unazad.
(06)
Pošaljite idempotency_key i ponovljeni poziv vraća originalnu poruku umesto da napravi drugu. Sama isporuka je bar jednom (at-least-once): ponovni pokušaj može ponovo stići do vaših klijenata, pa oni treba da deduplikuju po zaglavlju svix-id, koje je isto pri svakom pokušaju za istu poruku.
(Deo Nautilusa)
Isporuka webhookova je jedan deo Nautilusa, a ne zasebna usluga. Deli nalog i kontrolnu tablu sa prijavom i cron poslovima. Događaji prijave, poput nove registracije, stižu na vaš backend na isti način, kao potpisani webhookovi sa ponovnim pokušajima.
(Iskustvo programera)
Objavite događaj jednim pozivom — kroz zvanični SDK za Node, Python, PHP ili Rust, ili običnim HTTP zahtevom ako ne želite dodatnu zavisnost.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer $VERNE_RELAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "subscription.renewed",
"payload": { "user_id": "usr_987", "plan": "pro_tier" },
"idempotency_key": "evt_5f3c9a"
}'(FAQ)
Nautilus generiše jedinstvenu tajnu za svaki endpoint i potpisuje svaki odlazni zahtev pomoću HMAC SHA-256. Svaka isporuka nosi tri zaglavlja: svix-id, svix-timestamp i svix-signature. Potpis se računa preko svix-id, svix-timestamp i sirovog tela, spojenih tačkama, tako da primalac može da proveri autentičnost i odbije ponavljanje. Zvanične Svix biblioteke proveravaju sve to jednim pozivom.
Svaki odgovor različit od 2xx, i svaki timeout, računa se kao neuspeo pokušaj. Poruka se ponavlja po fiksnom rasporedu sa rastućim razmacima: 8 pokušaja u oko 28 sati, čime se štede serveri koji se još oporavljaju. Raspored je isti za sve endpointe i ne može se menjati. Endpoint koji ne uspe ni u jednom pokušaju pet dana se isključuje, a ništa vas ne obaveštava, pa povremeno pogledajte karticu Events. Kada se vaš server vrati, neuspele isporuke možete ponovo poslati iz kontrolne table, ili ponoviti sve što je palo od trenutka koji izaberete.
Da. Izložite svoj lokalni endpoint tunelom kao što su ngrok ili Cloudflare Tunnel i dodajte taj URL kao endpoint u kontrolnoj tabli. Koristite live ključ: događaji poslati test ključem se prihvataju, ali se ne isporučuju. Evidencija isporuka vam omogućava da pregledate svaki pokušaj dok testirate.
Možete, a to je mnogo više od POST-a: red i eksponencijalni backoff, tajne po endpointu i HMAC potpisivanje, način da se deduplicira ponovljeno slanje i evidencija isporuka koju vaša podrška može da pregleda kada klijent kaže da događaj nikada nije stigao. Nautilus ima tu listu već napravljenu, a vi plaćate po API zahtevu. Ono čega se odričete je kontrola: raspored ponovnih pokušaja je fiksan, endpointi se dodaju iz kontrolne table, a ne preko API-ja, a engine ispod je Svix, koji je open source ako ikada poželite da ga vodite sami.
Danas ne preko API-ja. Endpointi se kreiraju u kontrolnoj tabli, pa ako želite da vaši klijenti nalepe sopstveni URL u podešavanja vašeg proizvoda, taj ekran morate sami da napravite, a za sada neko sa pristupom kontrolnoj tabli dodaje URL. Objavljivanje događaja i njihovo čitanje nazad dostupni su preko API-ja.
(Počnite)
Isporuka webhookova je jedan deo Nautilusa: isti nalog i ista kontrolna tabla kao prijava i cron poslovi.
Koliko košta da se napravi
Izrada nije skupi deo. Red čekanja, retry sa backoff-om i pomoćnik za potpisivanje su nedelja posla, i većina timova tu stigne bez muke. Trošak počinje sledeće nedelje, kada klijent kaže da događaj nikada nije stigao, a odgovor na to znači ručno čitanje logova. I ne prestaje, jer je svaki novi klijentski endpoint novi način na koji isporuka može da propadne.
Uz to troši vašu pažnju tamo gde ništa ne donosi. Niko nije izabrao vaš proizvod zato što vaši retry-ji koriste eksponencijalni backoff. Ali webhook koji je tiho prestao da stiže prvo je tiket podrške, zatim razgovor o povraćaju novca, a ponekad i klijent koji odlazi. Velike posledice, nikakva zasluga — tačno oblik stvari koju vredi kupiti umesto praviti.
Ako biste radije sami pravili, napravite: dizajn nije tajna i mi bismo doneli većinu istih odluka. Samo ga računajte kao uslugu koju ćete voditi godinama, a ne kao sprint. Ako biste radije ne, endpoint koji već imate može da prima potpisane isporuke sa ponovnim pokušajima čim imate API ključ i njegov URL je u kontrolnoj tabli, a prvih 3.000 zahteva svakog meseca je besplatno.