# Webhooky

> Nechajte si oznámiť zmenu údajov firmy hneď, ako nastane. 31 typov udalostí, podpísané HMAC podpisom, s opakovaním pri zlyhaní.

Webhook obráti smer komunikácie. Namiesto toho, aby ste sa pravidelne pýtali, či sa niečo zmenilo, oznámime vám to sami – v čase, keď sa to stane.

## Prečo nie periodické dopytovanie

Kontrola tisícky firiem raz denne znamená tisíc volaní, z ktorých je drvivá väčšina zbytočná – väčšina firiem sa nemení. Zároveň je oneskorená až o celý deň. Webhook pošle požiadavku len vtedy, keď je čo oznámiť.

## Typy udalostí

K dispozícii je 31 typov udalostí. Pokrývajú zmenu základných údajov, zmenu štatutárov a spoločníkov, zápisy v Obchodnom vestníku, výskyt v zoznamoch dlžníkov, začatie insolvenčného konania, zmenu registrácie pre DPH a ďalšie. Odoberáte len tie, ktoré vás zaujímajú.

## Podpis a overenie

Každá požiadavka nesie hlavičku X-Webhook-Signature s HMAC podpisom tela vo formáte sha256=..., ďalej X-Webhook-Event s typom udalosti a X-Webhook-Delivery-Id s identifikátorom doručenia. Podpis overte pred spracovaním – je to jediný spôsob, ako mať istotu, že požiadavka prišla od nás.

## Opakovanie a spoľahlivosť

Ak váš endpoint neodpovie alebo vráti chybu, doručenie sa opakuje s narastajúcimi odstupmi. Identifikátor doručenia zostáva rovnaký, takže opakovanie viete rozpoznať a spracovať idempotentne. História doručení je dostupná v paneli aj cez API.

## Odporúčaný postup

Endpoint by mal overiť podpis, zapísať udalosť do vlastnej fronty a odpovedať 2xx čo najrýchlejšie. Spracovanie nechajte na pozadí. Endpoint, ktorý pred odpoveďou robí ťažkú prácu, zbytočne spôsobuje opakované doručenia.

## Časté otázky

### Čo sa stane, ak je môj server dočasne nedostupný?

Doručenie sa opakuje s narastajúcimi odstupmi. Ak endpoint dlhodobo zlyháva, upozorníme vás – doručenia sa nezahadzujú ticho.

### Ako overím podpis?

Vypočítajte HMAC SHA-256 zo surového tela požiadavky s vaším tajným kľúčom a porovnajte s hodnotou v X-Webhook-Signature. Porovnávajte funkciou odolnou voči časovému útoku.

### Môžem mať viac webhookov?

Áno. Rôzne endpointy pre rôzne typy udalostí sú bežné – napríklad rizikové udalosti do jedného systému a zmeny údajov do druhého.