Webhooks
Webhookovi su za tehnički napredne trgovce koji žele povezati WebShopHR s vlastitim sustavom: kad se nešto dogodi u tvojoj trgovini, WebShopHR odmah pošalje obavijest (HTTP POST) na URL koji zadaš. Korisno za automatizaciju: vlastito skladištenje, fakturiranje, CRM, Slack/e-mail obavijesti i slično.
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 Free/Pro/Enterprise.
Registracija webhooka
Gumb "Novi webhook" otvara dijalog gdje unosiš:
- URL: adresa tvog servera koja prima obavijesti (mora početi s
http://ilihttps://) - Događaji: na koje evente se pretplaćuješ (odaberi barem jedan)
order.createdorder.paidorder.refundedreturn.requestedTajni ključ i provjera potpisa
Prilikom kreiranja webhooka WebShopHR generira tajni ključ (secret) i prikazuje ga samo jednom: odmah ga zabilježi (u dijalogu je gumb za kopiranje), kasnije ga više nećeš moći vidjeti u CMS-u (isti princip kao kod poklon bonova). U popisu se zato vidi samo oznaka da je ključ postavljen, nikad sama vrijednost.
Svaki zahtjev koji WebShopHR pošalje na tvoj URL nosi X-Wshr-Signature header:
HMAC-SHA256 potpis sadržaja poruke (kriptografski otisak koji, bez tvog tajnog
ključa, nitko ne može krivotvoriti), izračunat tvojim tajnim ključem. Na svojoj
strani izračunaj isti potpis nad primljenim podatkom i usporedi s headerom:
ako se ne poklapaju, zahtjev nije stigao od WebShopHR-a (netko drugi ga je poslao ili
je sadržaj usput promijenjen) i trebaš ga odbaciti.
Format poruke
Svaka poruka je JSON s dva polja: event (naziv događaja) i data (podaci
narudžbe ili zahtjeva za povrat, iznosi su u centima, npr. 1250 = 12,50 €).
Zaštita od internih adresa
WebShopHR ne isporučuje webhookove na privatne, lokalne ili interne mrežne
adrese, čak i ako ih upišeš (npr. 192.168.x.x, 10.x.x.x, localhost,
127.0.0.1, i još nekoliko rjeđih rezerviranih raspona). Ovo je zaštita
protiv zloporabe, ne tehničko ograničenje koje bi te trebalo pogoditi u
normalnoj upotrebi: tvoj server mora biti dohvatljiv preko javnog interneta.
CMS ovu adresu ne provjerava pri spremanju: pogrešan ili interni URL sačuvat će se bez pritužbe, a odbijanje se dogodi tek pri stvarnoj isporuci. U logu isporuka takav pokušaj vidiš kao Neuspjelo, sa zadnjom greškom koja izričito spominje razlog. WebShopHR ne prati preusmjeravanja (redirecte): ako tvoj server odgovori s 3xx, to se tretira kao konačan odgovor, ne kao uputa kamo dalje poslati zahtjev.
Ponavljanje isporuke
Ako tvoj server ne odgovori odmah, WebShopHR pokušava isporučiti obavijest ponovno: najviše 5 pokušaja po isporuci, s 10 sekundi timeouta na svakom pozivu. Između pokušaja postoji eksponencijalni backoff, što znači da svaki sljedeći pokušaj čeka znatno duže od prethodnog, da se tvoj server može oporaviti od kratkog prekida.
Broj pokušaja za svaku isporuku vidiš u logu isporuka ispod popisa webhookova. Kad se svih 5 pokušaja potroši bez uspjeha, ta konkretna isporuka ostaje trajno neuspjela: CMS nema gumb da je ručno ponoviš. Sljedeći događaj istog tipa (npr. nova narudžba) isporučuje se normalno, neovisno o prethodnom neuspjehu.
Log isporuka
Ispod popisa webhookova CMS prikazuje zadnjih 50 isporuka svih tvojih webhookova (zbrojeno preko svih registriranih URL-ova, ne po webhooku): status, broj pokušaja i zadnju grešku ako isporuka nije uspjela. Koristi ovo za dijagnosticiranje kad obavijesti ne stižu na tvoj server.
Brisanje
Ikona kante na retku webhooka otvara potvrdu prije brisanja. Nakon brisanja WebShopHR više neće slati obavijesti na taj URL. Radnja je nepovratna, pa ako ti isti URL zatreba, registriraj webhook ponovno (dobit ćeš novi tajni ključ).
Javni API
Osim webhookova, WebShopHR ima i javnu OpenAPI dokumentaciju. Korisno ako umjesto (ili uz) primanje obavijesti želiš i sam dohvaćati podatke iz svog dućana.
Povezane stranice
