Web Hooks jsou způsob, jak se ve Vaší aplikaci v reálném čase dozvědět o změně v ABRA Flexi.
Princip je jednoduchý: Když dojde v databázi ABRA Flexi ke změně, je (obvykle v řádu několika málo vteřin) odeslán POST HTTP request na všechna zaregistrovaná URL.
Obsahem požadavku je výpis změn najednou od posledního zavolání hooku, a to ve stejném formátu, jaký získáte od ABRA Flexi přes rozhraní Changes API.
Postup
Musí být zapnuto Changes API (sledování změn).
Pokud nejste u nás v cloudu (při instalaci na vlastním serveru nebo na lokální instalaci), musí být hooky také povoleny v konfiguračním souboru ABRA Flexi Serveru flexibee-server.xml (umístění adresářů s flexibee-server.xml):
...<entry key="enableHooks">true</entry>....
Důvodem je, že při startu serveru je potřeba ihned nastartovat jádro (vizte též automatické startování jádra), což je časově náročná operace. Pozn.: pokud máte nastaveno enableHooks na true, není už třeba nastavovat startKernel.
Hook se zaregistruje PUT (příp. POST) požadavkem na adresu /c/{firma}/hooks s následujícími parametry:
povinné |
|
| URL, které se má zavolat |
| Formát dat (možné hodnoty jsou |
volitelné |
|
| Verze od které započne posílání následujích změn, tj. od nejbližší vyšší verze. Defaultní hodnota je rovna aktuální globální verzi ( |
| Libovolný řetězec, který bude odesílán s každou notifikací změn v HTTP hlavičce. Slouží k jednoduchému ověření, zda patří příchozí notifikace Vámi registrovanému hooku. Název klíče v HTTP hlavičce je |
| Potlačení testu funkčnosti předaného URL. |
Příklad:
curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687"
Registrace provádí test předaného URL odesláním prázdné notifikace. Při návratovém kódu jiném než 2xx nebude hook zaregistrován. Provedení testu lze potlačit parametrem skipUrlTest.
ABRA Flexi od verze 2017.1.1 podporuje SNI. To znamená, že je možně registrovat hooky směřující na HTTPS virtuální host.
Prozatím není možné specifikovat, kterých evidencí se má hook týkat, vždy je upozorněn na všechny změny, které v ABRA Flexi nastanou.
Jako obvykle, úspěch je oznámen stavovým kódem 200 a neúspěch kódem 400 (v odpovědi je textový popis příčiny).
Výpis zaregistrovaných hooků je na adrese /c/{firma}/hooks, odregistrovat hook lze DELETE požadavkem na adresu /c/{firma}/hooks/{id}.
Chování hooku při chybě
Pokud nastává chyba při zpracování hooku, pokouší se server zasílat požadavky opakovaně. Pokud hook i nadále selhává, začne docházet ke zpožďování volání hooků. Typicky v případě, že je služba zcela nedostupná začne každé volání později. Pro tyto účely se používá penalty, která reprezentuje dobu mezi jednotlivými pokusy.
Aktuální penalizaci můžete získat pomocí GET:
curl -u uzivatel:heslo -L -k "https://localhost:5434/c/{firma}/hooks/{id}.xml"
Vynulování penalizace a okamžité zavolání hooku zajistí PUT požadavek:
curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry"
Registrované hooky jsou ukládány v databázi a tak dojde k odeslání hooku i po restartování serveru. Služba garantuje, že se žádná změna neztratí a všechny jsou předány registrovanému hooku.
Doporučení pro implementaci hooku
Celý mechanismus funguje na principu best effort. To znamená, že i když se snažíme doručovat oznámení co nejdříve a vyhýbat se duplicitám, je potřeba počítat s tím, že zpoždění nebo duplicita mohou nastat (prostě stejný požadavek doručíme vícekrát). Pro eliminaci duplicit můžete zpracovávat globalVersion.
Zpracování hooku by mělo trvat co nejkratší dobu (< 15 sekund) a rozhodně nesmí přesáhnout 30 sekund, jinak se považuje volání za neúspěšné. Odpověď musí mít status kód 200 (resp. 2xx) a neměla by obsahovat žádné tělo. Pokud je některá z těchto podmínek porušena, daný hook je penalizován (tj. nějakou dobu nebude vůbec zavolán) a v krajním případě může dojít i k jeho úplnému vypnutí.
Ideální implementace hooku provádí pouze persistenci přijatých změn s případnou rychlou filtrací na relevatní změny a s přeskakovaním duplicit (již zpracovaných změn). Vlastní zpracování přijatých změn by mělo běžet asynchronně v nezávislém vlákně.
Další podporované stavové kódy odpovědí
Zpracování hooku podporuje v odpovědích, kromě klasického potvrzení statusem 200, ještě následující možnosti:
301 (Moved Permanently) / 308 (Permanent Redirect)V případě, že přesměrování vede na validní URL, tak proběhne aktualizace adresy registrovaného hooku a po krátké penalizaci již proběhne notifikace změn na nově evidovanou adresu.410 (Gone)Předpokládá se, že byl daný hook permanentně zrušen, a na straně ABRA Flexi proběhne jeho automatická odregistrace.