Web Hooks predstavujú spôsob, ako sa dozvedieť o zmenách v systéme ABRA Flexi vo vašej aplikácii v reálnom čase. Princíp je jednoduchý: keď v databáze ABRA Flexi dôjde k zmene, odošle sa požiadavka POST HTTP (zvyčajne v priebehu niekoľkých sekúnd) na všetky zaregistrované adresy URL. Obsahom požiadavky je výpis zmien naraz od posledného volania hooku v rovnakom formáte, aký získate z ABRA Flexi prostredníctvom rozhrania Changes API.

Rozhranie Changes API musí byť povolené. Hooky musia byť povolené aj v konfiguračnom súbore ABRA Flexi Server flexibee-server.xml(umiestnenie adresárov flexibee-server.xml):

Dôvodom je, že pri spustení servera je potrebné okamžite spustiť jadro (pozri tiež automatický štart jadra), čo je časovo náročná operácia. Poznámka: ak máte nastavenú hodnotu enableHooks na true, nie je potrebné nastavovať startKernel.

Web Hook sa zaregistruje pomocou požiadavky PUT (alebo POST) na adresu /c/{firm}/hooks s nasledujúcimi parametrami:

Napríklad:

Registrácia vykoná test odovzdanej adresy URL odoslaním prázdneho oznámenia. Ak je návratový kód iný ako 2xx, hook nebude zaregistrovaný. Vykonanie testu možno prepísať pomocou parametra skipUrlTest.

ABRA Flexi podporuje SNI od verzie 2017.1.1. To znamená, že je možné zaregistrovať hooky smerujúce na virtuálneho hostiteľa HTTPS.

Zatiaľ nie je možné určiť, na ktoré registrácie sa má hook odkazovať, vždy je upozornený na všetky zmeny, ktoré nastanú v systéme ABRA Flexi.

Úspech je ako zvyčajne oznámený stavovým kódom 200 a neúspech kódom 400 (odpoveď obsahuje textový popis príčiny).

Zoznam registrovaných hookov sa nachádza na adrese /c/{firma}/hooks, neregistrované hooky možno vyžiadať DELETE na adrese /c/{firma}/hooks/{id}.

Ak dôjde k chybe pri spracovaní hooks, server sa pokúsi opätovne odoslať požiadavky. Ak hook naďalej zlyháva, volania sa začnú oneskorovať. Ak je služba úplne nedostupná, každý hovor sa zvyčajne začne neskôr. Na tento účel sa používa pokuta, ktorá predstavuje čas medzi pokusmi.

Aktuálnu pokutu môžete získať pomocou funkcie GET:

Obnovenie trestu a okamžité volanie hookov zabezpečí požiadavku PUT:

Zaregistrované hooky sú uložené v databáze, takže hook bude odoslaný aj po reštarte servera. Služba zaručuje, že sa nestratia žiadne zmeny a všetky sa odovzdajú zaregistrovanému háku.

Celý mechanizmus funguje na princípe maximálneho úsilia. To znamená, že aj keď sa snažíme doručiť oznámenia čo najskôr a vyhnúť sa duplicitám, musíme počítať s tým, že môže dôjsť k oneskoreniu alebo duplicite (jednoducho doručíme tú istú požiadavku viackrát). Ak chcete odstrániť duplicitu, môžete spracovať globálnu verziu.

Spracovanie hooka by malo trvať čo najmenej času (< 15 sekúnd) a rozhodne nesmie presiahnuť 30 sekúnd, inak sa volanie považuje za neúspešné. Odpoveď musí mať stavový kód 200 (alebo 2xx) a nemala by obsahovať žiadne telo. Ak je niektorá z týchto podmienok porušená, hook je penalizovaný (t. j. určitý čas sa vôbec nevyvolá) a v krajnom prípade sa môže úplne vypnúť.

Ideálna implementácia hooka vykonáva len perzistenciu prijatých zmien s možným rýchlym filtrovaním relevantných zmien a vynechaním duplicít (už spracovaných zmien). Skutočné spracovanie prijatých zmien by malo prebiehať asynchrónne v nezávislom vlákne.

Okrem klasického potvrdenia stavu 200 podporuje spracovanie hookov v odpovediach nasledujúce možnosti:

301 (Moved Permanently) / 308 (Trvalé presmerovanie)V prípade, že presmerovanie vedie na platnú adresu URL, registrovaná adresa hooka sa aktualizuje a po krátkom treste sa zmeny oznámia na novo registrovanú adresu.410 (Gone)Predpokladá sa, že hook bol trvalo zrušený a na strane ABRA Flexi je automaticky odregistrovaný.