Webhooky — odběr událostí

Webhook je HTTP požadavek POST, který vám pošleme okamžitě po události v aplikaci — vystavení faktury, přijetí platby, atd. Vy v reakci aktualizujete svůj systém (CRM, e-shop, sklad).

Výhoda proti polling REST API: žádné dotazování — informaci dostanete během vteřin po události, bez opakovaného volání.

Aktuálně podporujeme 7 typů událostí:

• invoice.created — vytvořen nový koncept faktury
• invoice.issued — faktura vystavena (přidělené číslo)
• invoice.sent — faktura odeslána e-mailem
• invoice.paid — faktura uhrazena
• invoice.canceled — faktura stornována
• payment.created — zaznamenána platba
• contact.created — vytvořen nový kontakt (klient)

U jednoho webhooku můžete odebírat jednu nebo více událostí najednou.

V sekci Nástroje → Webhooky → Nový vyplňte:

• URL — endpoint na vaší straně (musí být HTTPS)
• Události — které chcete odebírat
• Popis — volitelný (např. „CRM sync produkce")

Po uložení dostanete unikátní secret (32 znaků). Uložte ho — slouží k ověření, že webhook přišel od nás.

Každý odeslaný webhook nese hlavičky:

• X-Webhook-Signature — HMAC-SHA256 hex podpis těla
• X-Webhook-Event — název události (např. invoice.paid)
• X-Webhook-Delivery-Id — UUID konkrétního doručení (pro deduplikaci)

Na vaší straně ověřte podpis přesně takto (Node.js):

const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
if (expected !== req.headers['x-webhook-signature']) throw 401;

Považujeme webhook za doručený, pokud vaše endpoint odpoví HTTP 2xx do 8 vteřin. Jakákoli jiná odpověď nebo timeout spustí retry.

Retry plán: 6 pokusů s exponenciálně rostoucími pauzami — 1 min, 5 min, 30 min, 2 h, 8 h, 24 h. Po 6 neúspěšných pokusech webhook označíme jako failed a najdete ho v Nástroje → Webhooky → Doručení. Můžete ho ručně přeposlat.

Deduplikace: díky X-Webhook-Delivery-Id snadno odfiltrujete duplicity, pokud váš endpoint odpoví pozdě a my mezitím retrnujeme.

V detailu webhooku najdete tlačítko „Odeslat testovací event" — pošleme vám syntetický payload pro vybranou událost. Skutečná data v aplikaci se nezmění.

Test se zaznamená do logu doručení, takže vidíte přesný request/response včetně podpisu — užitečné při debugování.