Webhook'ai

Webhook’ai skirti automatiškai pranešti jūsų sistemai apie svarbius įvykius (pvz., sukurtas/atnaujintas klientas, sąskaita, užsakymas, CRM įrašas ar pasikeitęs produkto kiekis).

Per API visą laiką jūs siunčiate užklausas, gaunate duomenų sąrašus ar kuriate naujus duomenis, tai per Webhook'us itax.lt sistema siunčia jūsų sistemai (nurodytu adresu) užklausas ir nedelsiant informuoja apie duomenų sukūrimą ar atnaujinimą itax.lt sistemoje.

Vietoje periodinių užklausų „polling“ (per API), gaunate realaus laiko POST užklausas su pasirašytu JSON savo nurodytu adresu (url), kad galėtumėte iškart sinchronizuoti duomenis, paleisti savo automatizacijas ar atnaujinti išorines sistemas.

Kaip susikurti webhook'ą?

Duomenys -> Integracijos -> Webhooks

Galite suskurti vieną webhook'ą visiems norimiems įvykiams arba atskirą kiekvienam įvykiui. Tai priklauso nuo to, kaip realizuosite užklausos "klausymą" ir apdorojimą savo serveryje.

Kokie galimi įvykių tipai?

Įvykių tipai savaime aiškūs pagal pavadinimus. Vienas yra kiek išskirtinis - product.qty_changed. Jis sužadinamas kai pasikeičia prekės kiekis. T.y. product.updated suveiks atnaujinus prekės kortelę, bet norint seksti prekės likutį, reikia naudoti product.qty_changed

client.created
client.updated
suplier.created
suplier.updated
invoice.created
invoice.updated
purchase.created
purchase.updated
product.created
product.updated
sales_quote.created
sales_quote.updated
sales_order.created
sales_order.updated
purchase_quote.created
purchase_quote.updated
purchase_order.created
purchase_order.updated
product.qty_changed
crm_deal.created
crm_deal.updated
crm_activity.created
crm_activity.updated

Įvykus nustatytam įvykiui itax.lt (pvz. sukūrus naują sąskaitą ar pasikeitus prekių likučiui), sistema nurodytu adresu siųs POST užklausą su įvykio pavadinimu bei sukurtu/atnaujintu objektu. Todėl nebūtina kurti atskirų url skirtingiems įvykiams, nes savo pusėje galite atpažinti kas įvyko ir gauti sukurto objekto duomenis.

itax.lt siunčia JSON su unikaliu id, type, created_at, data.object (serializuotas objektas), data.resource, data.id.

HTTP 2xx = sėkmė (jei jūsų serveris atsako 2xx http kodu, laikoma, kad webhooko užklausa įvykdyta sėkmingai).

Jei kitu kodu - nesėkmė. Tada užklausa kartojama iki 5 bandymų su uždelsimu 1,5,15,30,60 min. Po paskutinio nesėkmingo bandymo webhookas automatiškai deaktyvuojamas (jį rasite suarchyvuotą).

Parašas ir saugumas

Kaip patikrinti ar užklausa atėjo iš itax, o ne iš kitur?

Kiekvienoje užklausoje itax siunčia antraštes X-Itax-Signature ir X-Itax-Timestamp.

Parašas = HMAC SHA256 sujungiat X-Itax-Timestamp su body tašku ir pasirašoma jūsų signing_secret (webhooko slaptažodžiu).

Patikrinkite:

Nuskaitykite užklausos body (nepakeistą).

Patikrinkite, kad timestamp nėra pasenęs (pvz., >5 min).

Apskaičiuokite HMAC SHA256(webhook_slaptažodis, "#{X-Itax-Timestamp}.#{body}") ir palyginkite su X-Itax-Signature.

Čia vaizdingiau galite pamatyti ir pabandyti https://www.devglan.com/online-tools/hmac-sha256-online

Gauta užklausos antraštė

Rankiniu būdu patikriname parašą

Automatizuokite, kad jūsų serveris patikrintų užklausos parašą. Rankinis būdas pateiktas tik tam, kad suprastumėte algoritmą.

Webhook'ų užklausų testavimui rekomenduoju naudoti https://webhook.site/