Web Hooks

Web Hooks

Web Hooks jsou způsob, jak se ve Vaší aplikaci v reálném čase dozvědět o změně ve FlexiBee. Princip je jednoduchý: když dojde v databázi FlexiBee 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 FlexiBee přes rozhraní Changes API.

Postup

Musí být zapnuto Changes API (sledování změn). Také musí být hooky povoleny v konfiguračním souboru FlexiBee 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=http://muj.server.cz/hook.php URL, které se má zavolat
?format=XML Formát dat (možné hodnoty jsou XML a JSON)
volitelné
?lastVersion=123 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 (globalVersion) v momentě registrace hooku. Přípustné hodnoty jsou z intervalu: [0, globalVersion].
?secKey=MyHookSecretToken0687 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 X-FB-Hook-SecKey.
?skipUrlTest=true Potlačení testu funkčnosti předaného URL.

Např.:

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.

FlexiBee 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é ve FlexiBee 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ě FlexiBee proběhne jeho automatická odregistrace.