Webhook

Webhook umožňuje externímu systému automaticky přijímat upozornění na události, které nastanou v rámci systému reenio. Příjem události je realizován pomocí HTTP požadavku na URL adresu externího systému, a to podle nastavení vlastních zpráv v administraci. V těle požadavku jsou zaslány informace o dané události. Díky takto zaslané informaci může externí systém na danou událost okamžitě reagovat, a to například tím, že si pomocí API stáhne detailní informace.

Systém reenio implementuje webhooky pomocí vlastních zpráv.

Jak vypadá HTTP požadavek webhooku

Pro potřeby autorizace vůči externímu systému je možné v nastavení webhooku specifikovat také vlastní hlavičky HTTP požadavku. Jsou podporovány hlavičky s názvem začínajícím na "x-" nebo hlavička "authorization". Například pro integraci s platformou Make je vhodné využít autorizaci pomocí "x-make-apikey".

Data jsou zaslána ve formátu JSON pomocí HTTP POST metody (data se nacházejí v těle požadavku). Ukázka dat ve formátu JSON:

{  
    "triggerType": 1,  
    "customerId": 10,  
    "reservationId": 50  
}

Server, na který byl HTTP požadavek zaslán, musí vždy vrátit odpověď s HTTP stavovým kódem 200 (OK) a tělem odpovědi "REENIO" (prostý text, bez uvozovek). Pokud server vrátí jakoukoliv jinou odpověď je webhook považován za nedoručený a systém se jej bude snažit opětovně doručit, viz níže. Během konfigurace (nastavení vlastní zprávy v administraci) webhooku je na zadanou URL adresu zaslán ověřovací HTTP požadavek, který obsahuje prázdný objekt ve formátu JSON.

{}

Server musí na tento požadavek odpovědět stejně jako v případě jakéhokoliv jiného požadavku (stavový kód 200 a text "REENIO"), jinak se nastavení nepovede uložit.

Podporované protokoly pro zasílání webhooků jsou HTTP i HTTPS.

Data zaslaná jako tělo webhooku jsou vždy ve formátu JSON. Všechny požadavky, až na ověřovací (prázdný objekt), obsahují "triggerType", který udává typ události, která tento webhook vyvolala. Další vlastnosti záleží na typu události. Standardně je zasláno vždy (pokud exituje) ID rezervace ("reservationId") a ID zákazníka ("customerId"). Detailní informace svázané se zaslanými ID je následně možné získat přímou komunikací s API.

Množina zasílaných dat se může rozšířit či změnit.

Číselník hodnot triggerType

Hodnota	Událost
0	Vytvoření rezervace
1	Konec rezervovaného termínu
2	Změna stavu rezervace na: PROBĚHLA
3	Změna stavu rezervace na: POTVRZENÁ
4	Začátek rezervovaného termínu
5	Registraci zákazníka
6	Storno rezervace z důvodu neuhrazení
7	Uhrazení rezervace
8	Zrušení termínu z důvodu nenaplnění kapacity
9	Storno rezervace (kromě storna z důvodu neuhrazení a zrušení termínu)
10	Změna stavu rezervace na: NEPROBĚHLA
11	Změna stavu rezervace na: NEDORAZIL
12	Změna termínu rezervace
13	Konec rezervovaného termínu (ignoruje se, pokud existuje novější rezervace zákazníka)
14	Vytvoření rezervace jako náhradník
16	Začátek uhrazeného rezervovaného termínu
17	Náhradník přišel na řadu
20	Platba bankovním převodem za rezervaci - získání údajů pro platbu
21	Platba bankovním převodem za kredit - získání údajů pro platbu
22	Platba bankovním převodem za poukaz - získání údajů pro platbu
40	Poukazy - Přiřazení kódu zákazníkovi
41	Poukazy - Zakoupení kódu
42	Poukazy - Vznik kódu
43	Poukazy - Odstranění kódu
44	Poukazy - Dosažení maximálního počtu použití kódu
50	Zákaznický kredit - Přidání/odebrání kreditu (včetně zakoupení kreditu)
51	Zákaznický kredit - Přidání kreditu (včetně zakoupení kreditu)
52	Zákaznický kredit - Odebrání kreditu
53	Zákaznický kredit - Zakoupení kreditu
100-199	Změna stavu rezervace na vlastní stav
200	Systém - Nízký stav reenio kreditu
201	Systém - Expirace reenio balíčku

Co když bude URL pro zasílání webhooků nedostupná

Pokud URL vrátí jinou odpověď než je stavový kód 200 a text "REENIO", bude webhook považován za nedoručený a systém se jej bude pokoušet doručit s časovým odstupem znovu. Časový odstup se postupně zvyšuje s počtem neúspěšných pokusů o doručení. Přesný počet pokusů a časový odstup si rezervační systém definuje sám. Systém se vždy pokusí o doručení minimálně 3x, přičemž poslední pokus bude proveden minimálně po 12 hodinách od prvního pokusu. To by mělo pokrýt případný krátkodobý výpadek externího systému.

Server pro příjem webhooků by měl vždy odpovědět v nejkratším možném čase. Vyhněte se spouštění dlouho trvajících úloh v rámci volání a zpracování webhooku, resp. odpověď musí být zaslána co nejdříve po přijetí požadavku, nikoliv po kompletním zpracování úlohy. Pokud systém reenio neobdrží odpověď na zaslaný webhook v dostatečně krátkém čase, bude zaslání označeno jako neúspěšné.