Úvod do webhooků

Webhooky umožňují vaší aplikaci přijímat notifikace v reálném čase o událostech, které se dějí v systému Klubero. Místo pravidelného dotazování API (polling) vám Klubero automaticky odešle HTTP POST požadavek na vámi definovanou URL adresu, kdykoli nastane relevantní událost.

Quick Start

Zprovoznění webhooků ve 3 krocích:

1. Vytvořte endpoint

// Express.js příklad
app.post('/webhooks/klubero', (req, res) => {
  console.log('Událost:', req.body.event);
  console.log('Data:', req.body.data);
  res.status(200).send('OK');
});

2. Zaregistrujte webhook

curl -X POST "https://api.klubero.cz/api/v1.0/webhooks" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://vas-server.cz/webhooks/klubero",
    "event_types": ["ticket.created", "ticket.updated"]
  }'

3. Přijímejte události

{
  "event": "ticket.created",
  "entity_id": 12345,
  "occurred_at": "2024-01-15T10:30:00Z",
  "data": {
    "ticket_id": 12345,
    "event_title": "Koncert",
    "user_id": 789
  }
}

Testování lokálně

Pro testování na localhostu použijte nástroje jako ngrok nebo webhook.site.

---

Jak webhooky fungují?

┌─────────────┐                      ┌─────────────┐
│   Klubero   │  ───── HTTP POST ──► │    Vaše     │
│             │                      │  Aplikace   │
└─────────────┘                      └─────────────┘

1. V systému Klubero nastane událost (např. nákup vstupenky, registrace uživatele)
2. Na váš endpoint je odeslán HTTP POST požadavek s daty o události
3. Váš endpoint odpoví stavovým kódem 2xx pro potvrzení přijetí
4. Pokud doručení selže, požadavek je automaticky opakován (až 5×)

Klíčové vlastnosti

Vlastnost	Popis
Real-time notifikace	Okamžité informace o změnách bez nutnosti pollingu
HMAC-SHA256 podpisy	Volitelné ověření autenticity požadavků pomocí tajného klíče
Automatické retry	Při selhání až 5 opakovaných pokusů s rostoucími intervaly
Filtrování událostí	Přijímejte pouze ty typy událostí, které potřebujete
Logy doručení	Sledování historie doručení přes API

Podporované typy událostí

Uživatelé

• user.created – Nový uživatel byl vytvořen
• user.updated – Profil uživatele byl aktualizován
• user.deleted – Uživatel byl smazán

Vstupenky

• ticket.created – Nová vstupenka byla vytvořena
• ticket.updated – Vstupenka byla aktualizována
• ticket.deleted – Vstupenka byla smazána

Permanentní vstupenky

• permanent_ticket.created – Nová permanentka byla vytvořena
• permanent_ticket.updated – Permanentka byla aktualizována
• permanent_ticket.deleted – Permanentka byla smazána

Převody vstupenek

• ticket_transfer.created – Převod vstupenky byl zahájen
• ticket_transfer.accepted – Převod vstupenky byl přijat
• ticket_transfer.declined – Převod vstupenky byl odmítnut
• ticket_transfer.cancelled – Převod vstupenky byl zrušen odesílatelem

Vrácení vstupenek

• ticket_return.created – Vstupenka byla vrácena
• permanent_ticket_return.created – Permanentka byla vrácena

tip

Kompletní seznam všech typů událostí můžete získat přes API endpoint GET /api/v1.0/webhooks/event-types.

Požadavky na endpoint

Váš webhook endpoint musí splňovat následující požadavky:

Požadavek	Hodnota
Protokol	HTTPS (HTTP není podporováno)
Timeout	Odpověď do 10 sekund
Stavový kód	HTTP 2xx pro potvrzení úspěšného přijetí
Dostupnost	Veřejně dostupný z internetu

Zakázané URL adresy

Z bezpečnostních důvodů nelze registrovat webhooky na:

• Localhost (localhost, 127.0.0.1, ::1, 0.0.0.0)
• Interní domény (.local, .localhost, .internal, .intranet)
• Privátní IP adresy (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x)
• IPv6 link-local a site-local adresy

Důležité

Endpoint by měl odpovědět co nejrychleji a případné náročné zpracování provést asynchronně. Dlouhé zpracování může vést k timeoutu a opakovaným pokusům o doručení.

Autentizace a autorizace

Pro práci s webhooky potřebujete:

1. OAuth 2.0 přístupový token – Získaný pomocí Client Credentials flow
2. Oprávnění (scopes):
   • webhooks:read – Pro čtení webhooků a logů
   • webhooks:write – Pro vytváření, úpravu a mazání webhooků

Další kroky

1. Typy událostí – Detailní popis všech událostí
2. Konfigurace webhooků – Jak zaregistrovat webhook endpoint
3. Formát payloadu – Struktura dat v požadavcích
4. Zabezpečení – Jak ověřit autenticitu požadavků
5. Retry logika – Politika opakování při selhání