Web Hooks sú spôsob, ako sa vo vašej aplikácii v reálnom čase dozvedieť o zmene v ABRA Flexi. Princíp je jednoduchý: keď dôjde v databáze k zmene, je — zvyčajne v rádoch niekoľkých sekúnd — odoslaná požiadavka POST na všetky zaregistrované URL. Obsahom požiadavky je výpis zmien od posledného volania hooku, a to v rovnakom formáte, aký získate cez Changes API.

💡 Odosielanie notifikácií z Web Hooks sa nezapočítava do denného limitu API požiadaviek.

Postup

Aby hooky fungovali, musia byť splnené dve podmienky:

Zapnuté Changes API (sledovanie zmien).
Povolené hooky na serveri. To sa týka len inštalácií na vlastnom alebo lokálnom serveri — v našom cloude je nastavené za vás.

Na vlastnom serveri sa hooky povoľujú v konfiguračnom súbore flexibee-server.xml (kde ho nájsť):

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

Dôvodom je, že pri štarte servera je potrebné ihneď naštartovať jadro — časovo náročnú operáciu, viď automatické štartovanie jadra. Ak máte enableHooks nastavené na true, už nie je potrebné nastavovať startKernel.

⚠️ Pokiaľ hooky na serveri povolené nie sú, vracia celý endpoint /hooks — vrátane výpisu — chybu 400 s hlásením Hooks are not enabled in flexibee-server.xml.

Registrácia hooku

Hook sa zaregistruje požiadavkou PUT (prípadne POST) na adresu /c/{firma}/hooks s nasledujúcimi parametrami:

Parameter	Povinný	Význam
`url`	áno	URL, ktoré sa má zavolať — napríklad `http://muj.server.cz/hook.php`.
`format`	áno	Formát dát; možné hodnoty sú `XML` a `JSON`.
`lastVersion`	nie	Verzia, od ktorej sa začne posielanie nasledujúcich zmien, teda od najbližšej vyššej verzie. Predvolená hodnota sa rovná aktuálnej globálnej verzii (`globalVersion`) v momente registrácie hooku. Prípustné hodnoty sú z intervalu `[0, globalVersion]`.
`secKey`	nie	Ľubovoľný reťazec, ktorý bude odosielaný s každou notifikáciou zmien v HTTP hlavičke `X-FB-Hook-SecKey`. Slúži na jednoduché overenie, že prichádzajúca notifikácia patrí vami registrovanému hooku.
`skipUrlTest`	nie	S hodnotou `true` potlačí test funkčnosti odovzdaného URL.

Príklad registrácie:

PUT https://demo.flexibee.eu/c/demo/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687

Registrácia vykonáva test odovzdaného URL odoslaním prázdnej notifikácie. Pri návratovom kóde inom než 2xx nebude hook zaregistrovaný; test je možné potlačiť parametrom skipUrlTest. Ako obvykle je úspech oznámený kódom 200 a neúspech kódom 400, v ktorého odpovedi je textový popis príčiny.

ABRA Flexi od verzie 2017.1.1 podporuje SNI, takže je možné registrovať hooky smerujúce na HTTPS virtuálny host.

ℹ️ Nie je možné špecifikovať, ktorých evidencií sa má hook týkať — hook je vždy upozornený na všetky zmeny, ktoré v ABRA Flexi nastanú. Filtráciu na relevantné zmeny si musí zaistiť vaša aplikácia.

Výpis a odregistrácia

Výpis zaregistrovaných hookov je na adrese /c/{firma}/hooks, odregistrovať hook je možné požiadavkou DELETE na adresu /c/{firma}/hooks/{id}.

Správanie hooku pri chybe

Ak nastáva chyba pri spracovaní hooku, pokúša sa server zasielať požiadavky opakovane. Keď hook naďalej zlyháva, začne dochádzať k oneskoreniu jeho volania — typicky v prípade, že je služba úplne nedostupná, začne každé volanie neskôr. Na tieto účely sa používa penalty, ktorá reprezentuje dobu medzi jednotlivými pokusmi.

Aktuálnu penalizáciu vráti GET na konkrétny hook:

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

Vynulovanie penalizácie a okamžité zavolanie hooku zaistí požiadavka PUT:

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

Registrované hooky sú ukladané v databáze, takže k odoslaniu hooku dôjde aj po reštartovaní servera. Služba garantuje, že sa žiadna zmena nestratí a všetky sú odovzdané registrovanému hooku.

Odporúčania pre implementáciu hooku

Celý mechanizmus funguje na princípe best effort. To znamená, že aj keď sa snažíme doručovať oznámenia čo najskôr a vyhýbať sa duplicitám, je potrebné počítať s tým, že oneskorenie alebo duplicita môžu nastať — teda že rovnakú požiadavku doručíme viackrát. Pre elimináciu duplicít spracovávajte globalVersion.

🚨 Spracovanie hooku by malo trvať čo najkratšiu dobu (pod 15 sekúnd) a rozhodne nesmie presiahnuť 30 sekúnd, inak sa volanie považuje za neúspešné. Odpoveď musí mať status kód 200 (resp. 2xx) a nemala by obsahovať žiadne telo. Pri porušení niektorej z týchto podmienok je hook penalizovaný — nejakú dobu nebude vôbec zavolaný — a v krajnom prípade môže dôjsť aj k jeho úplnému vypnutiu.

Ideálna implementácia hooku vykonáva iba perzistenciu prijatých zmien s prípadnou rýchlou filtráciou na relevantné zmeny a s preskakovaním duplicít, teda už spracovaných zmien. Vlastné spracovanie prijatých zmien by malo bežať asynchrónne v nezávislom vlákne.

Ďalšie podporované stavové kódy odpovede

Okrem klasického potvrdenia statusom 200 podporuje spracovanie hooku v odpovediach ešte tieto možnosti:

Stavový kód odpovede	Čo urobí ABRA Flexi
`301 Moved Permanently` `308 Permanent Redirect`	Ak presmerovanie vedie na validné URL, aktualizuje sa adresa registrovaného hooku a po krátkej penalizácii prebehne notifikácia zmien na novo evidovanú adresu.
`410 Gone`	Predpokladá sa, že daný hook bol permanentne zrušený, a na strane ABRA Flexi prebehne jeho automatická odregistrácia.

Súvisiace

Sorodni članki