Webhooks za tvoje integracije

HTTP obavijest čim se nešto dogodi

Webhookovi su namijenjeni tehnički naprednim trgovcima koji žele povezati WebShopHR s vlastitim sustavom. Kad se nešto dogodi u trgovini, WebShopHR odmah pošalje HTTP POST obavijest na URL koji sam zadaš, umjesto da moraš ručno provjeravati je li stiglo nešto novo. To je korisno za automatizaciju poput vlastitog skladištenja, fakturiranja, CRM sustava ili Slack i e-mail obavijesti.

Ekran nalaziš u lijevoj navigaciji, u skupini Sustav. Uređivanje webhookova traži ulogu upravitelj ili vlasnik; obični član osoblja, djelatnik, tu nema pristupa. Značajka je dostupna na svim paketima, bez ograničenja između Besplatnog, Pro i Enterprise paketa, jer je namijenjena tehničkoj integraciji, ne razlici u opsegu prodaje.

Registracija webhooka i dostupni događaji

Gumb „Novi webhook” otvara dijalog s dva polja: URL adresu tvog servera koja prima obavijesti, koja mora početi s http:// ili https://, i popis događaja na koje se pretplaćuješ, od kojih moraš odabrati barem jedan. Dostupna četiri događaja prate životni ciklus narudžbe i povrata: order.created kada je nova narudžba zaprimljena, order.paid kada je narudžba označena plaćenom, order.refunded kada je narudžba djelomično ili potpuno refundirana, te return.requested kada kupac zatraži povrat. Svaki registrirani webhook u popisu prikazuje svoj URL, odabrane događaje kao chipove, status aktivnosti, oznaku je li tajni ključ postavljen i, ako je isporuka već pokušana, značku posljednjeg rezultata: isporučeno, neuspjelo ili u tijeku.

Tajni ključ vidiš samo jednom

Prilikom kreiranja webhooka WebShopHR generira tajni ključ i prikazuje ga samo tog trenutka, u obliku koji počinje s whsec_ i nastavlja se nizom heksadecimalnih znakova. Dijalog ima gumb za kopiranje: ključ treba odmah zabilježiti, jer ga kasnije više nećeš moći vidjeti u CMS-u, isti princip kao kod koda poklon bona. U popisu webhookova poslije se vidi samo oznaka da je ključ postavljen, nikad sama vrijednost. Svaki zahtjev koji WebShopHR pošalje tvom URL-u nosi zaglavlje X-Wshr-Signature, HMAC-SHA256 potpis sadržaja poruke izračunat tvojim tajnim ključem. Na svojoj strani izračunaš isti potpis nad primljenim podatkom i usporediš ga sa zaglavljem; ako se ne poklapaju, zahtjev nije stigao od WebShopHR-a i treba ga odbaciti.

Poruka nosi naziv događaja i njegove podatke

Svaka poslana poruka je JSON s dva polja: event, naziv događaja, i data, podaci narudžbe ili zahtjeva za povrat. Iznosi u poruci su izraženi u centima, primjerice broj 1250 znači 12,50 eura, kako bi se izbjeglo zaokruživanje decimalnih brojeva na tvojoj strani. Format je isti za sva četiri događaja, pa tvoj sustav prepoznaje vrstu poruke čitanjem polja event, bez potrebe za posebnim parsiranjem za svaki slučaj.

WebShopHR ne isporučuje na privatne i interne adrese

Iz sigurnosnih razloga WebShopHR ne isporučuje webhookove na privatne, lokalne ili interne mrežne adrese, čak i ako ih upišeš, primjerice adrese u rasponu 192.168.x.x, 10.x.x.x, localhost, 127.0.0.1 i još nekoliko rjeđih rezerviranih raspona. Ovo je zaštita od zloupotrebe, ne ograničenje koje bi trebalo pogoditi normalnu upotrebu: tvoj server mora biti dohvatljiv preko javnog interneta. CMS URL sprema odmah; provjera adrese stiže tek pri stvarnoj isporuci, gdje pogrešnu ili internu adresu vidiš u logu kao neuspjelo, s greškom koja izričito navodi razlog. WebShopHR ne prati preusmjeravanja: ako tvoj server odgovori s 3xx statusom, to se tretira kao konačan odgovor, ne kao uputa kamo dalje poslati zahtjev.

Do pet pokušaja isporuke, uz zapisan trag u logu

Ako tvoj server ne odgovori na vrijeme, WebShopHR pokušava isporučiti obavijest ponovno, najviše pet puta po isporuci. Između pokušaja postoji eksponencijalni razmak, pa svaki sljedeći pokušaj čeka znatno duže od prethodnog, dajući tvom serveru vremena da se oporavi od kratkog prekida. Kad se svih pet pokušaja potroši bez uspjeha, ta konkretna isporuka ostaje trajno neuspjela u logu; sljedeći događaj istog tipa isporučuje se normalno, neovisno o prethodnom neuspjehu. Ispod popisa webhookova CMS prikazuje zadnjih pedeset isporuka, zbrojeno preko svih tvojih registriranih URL-ova, s njihovim statusom, brojem pokušaja i zadnjom greškom ako isporuka nije uspjela; taj log koristiš za dijagnosticiranje kad obavijesti ne stižu.

Webhook gura podatke, javni API ih daješ na zahtjev

Webhook i javni API rješavaju obrnute smjerove iste potrebe za integracijom. Webhook sam, bez tvog upita, gura obavijest prema tvom serveru čim se nešto dogodi, pa je prikladan kad vlastiti sustav treba reagirati odmah na novu narudžbu, plaćanje ili zahtjev za povrat. Javni API čekaš da ga sam pozoveš kad god trebaš dohvatiti trenutačno stanje, primjerice popis narudžbi ili artikala, neovisno o tome je li se nešto upravo promijenilo.

Dvije mogućnosti nisu isključive. Webhook ti javlja da se nešto dogodilo, a javni API zatim možeš pozvati da dohvatiš pune, ažurne detalje tog zapisa, umjesto da cijeli sadržaj narudžbe ili zahtjeva pokušavaš izvući samo iz same webhook poruke.

Brisanje je trajno, a podaci ostaju dostupni i kroz javni API

Ikona kante uz redak webhooka otvara potvrdu prije brisanja. Nakon brisanja WebShopHR više ne šalje obavijesti na taj URL, a radnja je nepovratna: zatreba li ti isti URL ponovno, webhook registriraš iznova i dobivaš novi tajni ključ. Osim webhookova, WebShopHR ima i javnu OpenAPI dokumentaciju, dostupnu na /api/docs, korisnu ako umjesto primanja obavijesti, ili uz njih, želiš i sam dohvaćati podatke iz svog dućana.

Webhookovi zato daju izravan, potpisan kanal prema tvom sustavu, bez potrebe da netko ručno prati CMS ili izvozi podatke. Registracija je jednostavna, ali odgovornost za provjeru potpisa, dohvatljivost servera i praćenje loga isporuka ostaje na tebi; kad su URL i događaji ispravno postavljeni, obavijesti stižu automatski, uz jasan trag onoga što je poslano i kako je prošlo.