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 ke změně, je — obvykle v řádu několika vteřin — odeslán požadavek POST na všechna zaregistrovaná URL. Obsahem požadavku je výpis změn od posledního zavolání hooku, a to ve stejném formátu, jaký získáte přes Changes API.

💡 Odesílání notifikací z Web Hooks se nezapočítává do denního limitu API požadavků.

Postup

Aby hooky fungovaly, musí být splněné dvě podmínky:

Zapnuté Changes API (sledování změn).
Povolené hooky na serveru. To se týká jen instalací na vlastním nebo lokálním serveru — v našem cloudu je nastaveno za vás.

Na vlastním serveru se hooky povolují v konfiguračním souboru flexibee-server.xml (kde jej najít):

...
<entry key="enableHooks">true</entry>
...

Důvodem je, že při startu serveru je potřeba ihned nastartovat jádro — časově náročnou operaci, viz automatické startování jádra. Máte-li enableHooks nastavené na true, není už třeba nastavovat startKernel.

⚠️ Dokud hooky na serveru povolené nejsou, vrací celý endpoint /hooks — včetně výpisu — chybu 400 s hlášením Hooks are not enabled in flexibee-server.xml.

Registrace hooku

Hook se zaregistruje požadavkem PUT (případně POST) na adresu /c/{firma}/hooks s následujícími parametry:

Parametr	Povinný	Význam
`url`	ano	URL, které se má zavolat — například `http://muj.server.cz/hook.php`.
`format`	ano	Formát dat; možné hodnoty jsou `XML` a `JSON`.
`lastVersion`	ne	Verze, od které započne posílání následujících změn, tedy od nejbližší vyšší verze. Výchozí hodnota je rovna aktuální globální verzi (`globalVersion`) v momentě registrace hooku. Přípustné hodnoty jsou z intervalu `[0, globalVersion]`.
`secKey`	ne	Libovolný řetězec, který bude odesílán s každou notifikací změn v HTTP hlavičce `X-FB-Hook-SecKey`. Slouží k jednoduchému ověření, že příchozí notifikace patří vámi registrovanému hooku.
`skipUrlTest`	ne	S hodnotou `true` potlačí test funkčnosti předaného URL.

Příklad registrace:

PUT https://demo.flexibee.eu/c/demo/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; test lze potlačit parametrem skipUrlTest. Jako obvykle je úspěch oznámen kódem 200 a neúspěch kódem 400, v jehož odpovědi je textový popis příčiny.

ABRA Flexi od verze 2017.1.1 podporuje SNI, takže je možné registrovat hooky směřující na HTTPS virtuální host.

ℹ️ Není možné specifikovat, kterých evidencí se má hook týkat — hook je vždy upozorněn na všechny změny, které v ABRA Flexi nastanou. Filtraci na relevantní změny si musí zajistit vaše aplikace.

Výpis a odregistrace

Výpis zaregistrovaných hooků je na adrese /c/{firma}/hooks, odregistrovat hook lze požadavkem DELETE 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ě. Když hook i nadále selhává, začne docházet ke zpožďování jeho volání — 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 vrátí GET na konkrétní hook:

GET https://demo.flexibee.eu/c/demo/hooks/{id}.xml

Vynulování penalizace a okamžité zavolání hooku zajistí požadavek PUT:

PUT https://demo.flexibee.eu/c/demo/hooks/{id}/retry

Registrované hooky jsou ukládány v databázi, takže k odeslání hooku dojde 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 — tedy že stejný požadavek doručíme vícekrát. Pro eliminaci duplicit zpracovávejte globalVersion.

🚨 Zpracování hooku by mělo trvat co nejkratší dobu (pod 15 sekund) a rozhodně nesmí přesáhnout 30 sekund, jinak se volání považuje za neúspěšné. Odpověď musí mít status kód 200 (resp. 2xx) a neměla by obsahovat žádné tělo. Při porušení některé z těchto podmínek je hook penalizován — 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 relevantní změny a s přeskakováním duplicit, tedy 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í

Kromě klasického potvrzení statusem 200 podporuje zpracování hooku v odpovědích ještě tyto možnosti:

Stavový kód odpovědi	Co udělá ABRA Flexi
`301 Moved Permanently` `308 Permanent Redirect`	Vede-li přesměrování na validní URL, aktualizuje se adresa registrovaného hooku a po krátké penalizaci 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.

Související

Související články