Konfigurace webhooků

Tato stránka popisuje, jak zaregistrovat a spravovat webhooky pomocí Klubero API.

Autentizace

Všechny endpointy vyžadují OAuth 2.0 Bearer token s příslušnými oprávněními:

Operace	Požadované oprávnění
Čtení webhooků a logů	`webhooks:read`
Vytváření, úprava, mazání	`webhooks:write`

Registrace webhooku

Pro registraci nového webhooku použijte endpoint POST /api/v1.0/webhooks.

Požadavek

curl -X POST "https://api.klubero.cz/api/v1.0/webhooks" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/klubero",
    "secret": "muj-tajny-klic",
    "event_types": ["user.created", "user.updated", "ticket.created"],
    "description": "Produkční webhook",
    "active": true
  }'

Parametry požadavku

Parametr	Typ	Povinný	Popis
`url`	string	Ano	HTTPS URL vašeho endpointu (max 2048 znaků)
`secret`	string	Ne	Tajný klíč pro HMAC podpis (max 255 znaků)
`event_types`	array	Ano	Seznam typů událostí, které chcete přijímat
`description`	string	Ne	Popis webhooku (max 500 znaků)
`active`	boolean	Ne	Zda je webhook aktivní (výchozí: `true`)

Validace URL

URL musí splňovat následující požadavky:

HTTPS protokol – HTTP není podporováno
Veřejně dostupná – Nelze použít localhost ani privátní IP adresy
Platný formát – Musí být validní URL

Zakázané URL:

localhost, 127.0.0.1, ::1, 0.0.0.0
Domény končící na .local, .localhost, .internal, .intranet
Privátní IP rozsahy: 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x
IPv6 link-local a site-local adresy

Odpověď

{
  "success": true,
  "data": {
    "id": 123,
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "your-oauth-client-id",
    "url": "https://example.com/webhooks/klubero",
    "has_secret": true,
    "event_types": ["user.created", "user.updated", "ticket.created"],
    "description": "Produkční webhook",
    "active": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Důležité

Hodnotu secret si bezpečně uložte při vytvoření! V odpovědích API je zobrazeno pouze has_secret: true/false, nikdy skutečná hodnota. Secret nelze později získat, pouze změnit.

Získání seznamu webhooků

Pro získání všech vašich webhooků použijte endpoint GET /api/v1.0/webhooks.

Požadavek

curl -X GET "https://api.klubero.cz/api/v1.0/webhooks?page=1&pageSize=20&active=true" \
  -H "Authorization: Bearer {access_token}"

Parametry dotazu

Parametr	Typ	Výchozí	Popis
`page`	int	1	Číslo stránky
`pageSize`	int	20	Počet záznamů na stránku (max 100)
`active`	bool	-	Filtrovat podle stavu aktivace

Odpověď

{
  "success": true,
  "data": [
    {
      "id": 123,
      "guid": "550e8400-e29b-41d4-a716-446655440000",
      "client_id": "your-oauth-client-id",
      "url": "https://example.com/webhooks/klubero",
      "has_secret": true,
      "event_types": ["user.created", "user.updated", "ticket.created"],
      "description": "Produkční webhook",
      "active": true,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  }
}

Získání detailu webhooku

Pro získání detailu konkrétního webhooku použijte endpoint GET /api/v1.0/webhooks/{id}.

Požadavek

curl -X GET "https://api.klubero.cz/api/v1.0/webhooks/123" \
  -H "Authorization: Bearer {access_token}"

Odpověď

{
  "success": true,
  "data": {
    "id": 123,
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "your-oauth-client-id",
    "url": "https://example.com/webhooks/klubero",
    "has_secret": true,
    "event_types": ["user.created", "user.updated", "ticket.created"],
    "description": "Produkční webhook",
    "active": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Aktualizace webhooku

Pro aktualizaci existujícího webhooku použijte endpoint PATCH /api/v1.0/webhooks/{id} s JSON Patch operacemi.

Požadavek

curl -X PATCH "https://api.klubero.cz/api/v1.0/webhooks/123" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    { "op": "replace", "path": "/url", "value": "https://newurl.com/webhooks" },
    { "op": "replace", "path": "/active", "value": false },
    { "op": "replace", "path": "/event_types", "value": ["ticket.created", "ticket.updated"] }
  ]'

JSON Patch operace

Operace	Popis
`replace`	Nahradí hodnotu pole
`add`	Přidá hodnotu (pro pole event_types)
`remove`	Odstraní hodnotu

Upravitelná pole

Pole	Typ	Popis
`/url`	string	Nová URL adresa (validace se aplikuje)
`/secret`	string	Nový tajný klíč
`/event_types`	array	Nový seznam typů událostí
`/description`	string	Nový popis
`/active`	boolean	Aktivovat/deaktivovat webhook

Odpověď

{
  "success": true,
  "data": {
    "id": 123,
    "guid": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "your-oauth-client-id",
    "url": "https://newurl.com/webhooks",
    "has_secret": true,
    "event_types": ["ticket.created", "ticket.updated"],
    "description": "Produkční webhook",
    "active": false,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Smazání webhooku

Pro smazání webhooku použijte endpoint DELETE /api/v1.0/webhooks/{id}.

Požadavek

curl -X DELETE "https://api.klubero.cz/api/v1.0/webhooks/123" \
  -H "Authorization: Bearer {access_token}"

Odpověď

{
  "success": true
}

Logy webhooků

Pro sledování doručení a jejich stavů můžete získat logy webhooku.

Požadavek

curl -X GET "https://api.klubero.cz/api/v1.0/webhooks/123/logs?page=1&pageSize=20&status=failed" \
  -H "Authorization: Bearer {access_token}"

Parametry dotazu

Parametr	Typ	Výchozí	Popis
`page`	int	1	Číslo stránky
`pageSize`	int	20	Počet záznamů na stránku (max 100)
`status`	string	-	Filtrovat: `pending`, `delivered`, `failed`

Odpověď

{
  "success": true,
  "data": [
    {
      "id": 456,
      "guid": "660e8400-e29b-41d4-a716-446655440001",
      "webhook_id": 123,
      "event_type": "user.created",
      "entity_id": 789,
      "status": "delivered",
      "attempts": 1,
      "last_attempt": "2024-01-15T10:30:05Z",
      "next_retry": null,
      "response_code": 200,
      "error_message": null,
      "duration_ms": 125,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 455,
      "guid": "660e8400-e29b-41d4-a716-446655440002",
      "webhook_id": 123,
      "event_type": "ticket.created",
      "entity_id": 98765,
      "status": "failed",
      "attempts": 5,
      "last_attempt": "2024-01-15T14:30:00Z",
      "next_retry": null,
      "response_code": 500,
      "error_message": "Internal Server Error",
      "duration_ms": 5023,
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 150,
    "totalPages": 8
  }
}

Stavy doručení

Stav	Popis
`pending`	Čeká na doručení nebo na další pokus
`delivered`	Úspěšně doručeno
`failed`	Doručení selhalo po všech pokusech

Chybové odpovědi

400 Bad Request

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "URL must use HTTPS protocol"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Webhook with ID 123 was not found"
  }
}

Limity

Limit	Hodnota
Maximální délka URL	2048 znaků
Maximální délka secret	255 znaků
Maximální délka description	500 znaků
Maximální pageSize	100

Autentizace​

Registrace webhooku​

Požadavek​

Parametry požadavku​

Validace URL​

Odpověď​

Získání seznamu webhooků​

Požadavek​

Parametry dotazu​

Odpověď​

Získání detailu webhooku​

Požadavek​

Odpověď​

Aktualizace webhooku​

Požadavek​

JSON Patch operace​

Upravitelná pole​

Odpověď​

Smazání webhooku​

Požadavek​

Odpověď​

Logy webhooků​

Požadavek​

Parametry dotazu​

Odpověď​

Stavy doručení​

Chybové odpovědi​

400 Bad Request​

404 Not Found​

Limity​

Autentizace

Registrace webhooku

Požadavek

Parametry požadavku

Validace URL

Odpověď

Získání seznamu webhooků

Požadavek

Parametry dotazu

Odpověď

Získání detailu webhooku

Požadavek

Odpověď

Aktualizace webhooku

Požadavek

JSON Patch operace

Upravitelná pole

Odpověď

Smazání webhooku

Požadavek

Odpověď

Logy webhooků

Požadavek

Parametry dotazu

Odpověď

Stavy doručení

Chybové odpovědi

400 Bad Request

404 Not Found

Limity