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 ABRA Flexi k zmene, je (zvyčajne v priebehu niekoľkých sekúnd) odoslaný POST HTTP request na všetky zaregistrované URL.
Obsahom požiadavky je výpis zmien naraz od posledného zavolania hooku, a to v rovnakom formáte, aký získate od ABRA Flexi cez rozhranie Changes API.
Poznámka:
Odosielanie notifikácií z WebHooks sa nezapočítava do denného limitu API requestov.
Postup
Musí byť zapnuté Changes API (sledovanie zmien).
Pokiaľ nie ste u nás v cloude (pri inštalácii na vlastnom serveri alebo pri lokálnej inštalácii), musia byť hooky tiež povolené v konfiguračnom súbore ABRA Flexi Servera flexibee-server.xml (umiestnenie adresárov s flexibee-server.xml):
...<entry key="enableHooks">true</entry>....
Dôvodom je, že pri štarte servera je potrebné ihneď naštartovať jadro (pozri tiež automatické štartovanie jadra), čo je časovo náročná operácia. Pozn.: ak máte nastavené enableHooks na true, nie je už potrebné nastavovať startKernel.
Hook sa zaregistruje PUT (príp. POST) požiadavkou na adresu /c/{firma}/hooks s nasledujúcimi parametrami:
povinné |
|
URL, ktoré sa má zavolať | |
| Formát dát (možné hodnoty sú |
voliteľné |
|
| Verzia, od ktorej sa začne odosielanie nasledujúcich zmien, t. j. od najbližšej vyššej verzie. Predvolená hodnota sa rovná aktuálnej globálnej verzii ( |
| Ľubovoľný reťazec, ktorý bude odosielaný s každou notifikáciou zmien v HTTP hlavičke. Slúži na jednoduché overenie, či patrí prichádzajúca notifikácia Vami registrovanému hooku. Názov kľúča v HTTP hlavičke je |
| Potlačenie testu funkčnosti zadanej URL. |
Prí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"
Registrácia vykoná test zadanej URL odoslaním prázdnej notifikácie. Pri návratovom kóde inom ako 2xx nebude hook zaregistrovaný. Vykonanie testu možno potlačiť parametrom skipUrlTest.
ABRA Flexi od verzie 2017.1.1 podporuje SNI. To znamená, že je možné registrovať hooky smerujúce na HTTPS virtuálny host.
Zatiaľ nie je možné špecifikovať, ktorých evidencií sa má hook týkať, vždy je upozornený na všetky zmeny, ktoré v ABRA Flexi nastanú.
Ako obvykle, úspech je oznámený stavovým kódom 200 a neúspech kódom 400 (v odpovedi je textový popis príčiny).
Výpis zaregistrovaných hookov je na adrese /c/{firma}/hooks, odhlásiť hook možno DELETE požiadavkou na adresu /c/{firma}/hooks/{id}.
Správanie hooku pri chybe
Ak nastáva chyba pri spracovaní hooku, server sa pokúša odosielať požiadavky opakovane. Pokiaľ hook naďalej zlyháva, začne dochádzať k oneskoreniu volaní hookov. Typicky v prípade, keď je služba úplne nedostupná, začne každé volanie neskôr. Na tieto účely sa používa penalty, ktorá reprezentuje čas medzi jednotlivými pokusmi.
Aktuálnu penalizáciu môžete získať pomocou GET:
curl -u uzivatel:heslo -L -k "https://localhost:5434/c/{firma}/hooks/{id}.xml"
Vynulovanie penalizácie a okamžité zavolanie hooku zabezpečí PUT požiadavka:
curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry"
Zaregistrované hooky sú ukladané v databáze, a tak dôjde k odoslaniu hooku aj po reštartovaní servera. Služba garantuje, že sa žiadna zmena nestratí a všetky sú odovzdané zaregistrované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ť (jednoducho rovnakú požiadavku doručíme viackrát). Na elimináciu duplicít môžete spracovávať globalVersion.
Spracovanie hooku by malo trvať čo najkratší čas (< 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 (resp. 2xx) a nemala by obsahovať žiadne telo. Ak je niektorá z týchto podmienok porušená, daný hook je penalizovaný (t. j. 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 relevantných zmien a s preskakovaním duplicít (už spracovaných zmien). Vlastné spracovanie prijatých zmien by malo prebiehať asynchrónne v nezávislom vlákne.
Ďalšie podporované stavové kódy odpovedí
Spracovanie hooku podporuje v odpovediach, okrem klasického potvrdenia statusom 200, ešte nasledujúce možnosti:
301 (Moved Permanently) / 308 (Permanent Redirect)V prípade, že presmerovanie vedie na platnú URL, dôjde k aktualizácii adresy zaregistrované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.