Vyzkoušet zdarma
ÚvodPlatformaCeníkOtázkyNápovědaKontakt Kivea FlexiKivea PohodaKivea účetnictvíKivea fakturace Vyzkoušet zdarma

Co to je?

Poznámka správce: Toto je “systém upozornění”, který proaktivně odesílá aktualizace z vašeho {productName} do vašich dalších aplikací v okamžiku, kdy se stanou. Namísto toho, aby se vaše další systémy ptaly “Je tu něco nového?”, náš systém jim zavolá a řekne “Hej, tady je to, co se právě změnilo!”

Pro koho je to určeno? Administrátoři by si to měli přečíst, aby pochopili, jak povolit automatizaci v reálném čase ve svém podnikání. I když můžete vidět aktivní webhooky ve svém nastavení, technické nastavení (URL a zpracování payloadu) musí provést vývojář, který dokáže vytvořit “posluchače” pro tato oznámení.

Klíčové výhody pro e-shop:

  • Okamžité aktualizace: Udržujte svůj sklad, dopravu nebo nástroje CRM aktualizované během několika sekund od nové objednávky nebo změny stavu zásob.
  • Chytré filtrování: Odesílejte upozornění pouze na věci, na kterých záleží (např. “informuj mě pouze o nových objednávkách” nebo “informuj mě pouze o změně ceny produktu”).
  • Spolehlivé doručení: Pokud je váš jiný systém dočasně mimo provoz, náš systém se bude snažit odeslat oznámení, dokud se mu to nepodaří.
  • Efektivní automatizace: Tím, že odesíláte data pouze v případě, že se změní, ušetříte náklady na server a zajistíte, že vaše integrace budou co nejrychlejší.

Přehled

Webhooky umožňují vaší aplikaci přijímat oznámení v reálném čase, když dojde ke změnám dat v systému. Jsou ideální pro udržování synchronizace externích systémů s vašimi daty.

**Klíčové vlastnosti**
- Dávkové doručování: Změny se shromažďují po dobu 5 sekund a odesílají se v dávkách (až 100 změn)
- Pokročilé filtrování: Filtrování na základě entity, pole a sloupce
- Spolehlivé doručování: Automatické opakování s exponenciálním zpožděním (1min → 3min → 9min → 27min → 81min)
- Seskupování ChangeSet: Změny jsou seskupeny podle changeSet pro transakční konzistenci

Jak to funguje

1. Změny dat

Když dojde ke změnám dat (operace create, update, delete), systém tyto změny zachytí.

2. 5sekundové dávkovací okno

Změny se shromažďují po dobu 5 sekund po první změně, aby se vytvořily efektivní dávky.

3. Filtrování a seskupování

Změny se filtrují na základě konfigurace webhooku (entita, where, columns) a seskupují se podle changeSet pro konzistenci.

4. Doručování HTTP POST

Payload webhooku se odesílá jako HTTP POST do vašeho koncového bodu s až 100 změnami na požadavek.

Příklady registrace webhooků

Zjistěte, jak registrovat webhooky s různými konfiguracemi

Registrace základního webhooku

Vytvořte webhook pro změny entity [badge:Registration|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook"
}

Webhook s filtrem entity

Přijímejte webhooky pouze pro konkrétní entity [badge:Filtering|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "units",
    "url": "https://your-api.com/webhooks/units",
    "action": "webhook"
}

Webhook s filtrem Where

Filtrujte změny na základě hodnot polí [badge:Filtering|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "filter": "price > 100 AND status = 'active'"
}

Webhook s filtrem sloupců

Spusťte webhook pouze při změně konkrétních sloupců [badge:Filtering|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "columns": ["price", "status", "inventory_count"]
}

Webhook pro všechny entity

Přijímejte oznámení o všech změnách entity [badge:Registration|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": null,
    "url": "https://your-api.com/webhooks/all-changes",
    "action": "webhook"
}

Webhook s řízením ChangeSet

Řídí, zda zahrnout změny v rámci changeSetů [badge:Advanced|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "allowInChangeSet": true,
    "disabled": false
}

Webhook s doručením payloadu

Vloží aktuální stav každého změněného záznamu přímo do payloadu [badge:Advanced|info|right]

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "sendPayload": true
}

sendPayload můžete kombinovat s jakýmikoli jinými možnostmi filtru:

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "sendPayload": true,
    "columns": ["price", "status"],
    "filter": "status = 'active'"
}

Webhook s columnsToSend

Přesně ovládejte, která pole (a související data) jsou zahrnuta v payloadu data [badge:Advanced|info|right]

Když je nastaveno columnsToSend, systém to použije jako dotaz pro výběr sloupců – může zahrnovat rozšíření relací. Pokud je columnsToSend prázdné (nebo vynechané), vrátí se celý záznam.

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook",
    "sendPayload": true,
    "columnsToSend": ["id", "name", "price", "status", "category.name"]
}

Funkce filtrování

Řídí, které změny spustí vaše webhooky

card: Filtr entity
icon: filter
Filtrujte podle konkrétního typu entity. Nastavte pole "entity" pro příjem webhooků pouze pro konkrétní entity, jako jsou "products", "units" atd. Použijte null pro příjem všech změn entity.
card: Filtr Where
icon: code
Pokročilé filtrování na základě polí. Použijte klauzule where podobné SQL k filtrování změn na základě hodnot polí. Příklad: "price > 100 AND status = 'active'"
card: Filtr sloupců
icon: filter
Filtrujte podle konkrétních změn sloupců. Použijte pole "columns" pro spuštění webhooků pouze v případě, že se skutečně změnily konkrétní sloupce. Příklad: ["price", "status", "inventory_count"]
card: Řízení ChangeSet
icon: play
Zahrňte nebo vylučte data changeSet. Řídí, zda jsou zahrnuty změny v rámci changeSetů pomocí pole "allowInChangeSet" (true/false).
card: Doručení payloadu
icon: database
Vloží aktuální stav záznamu do každé položky změny. Když je "sendPayload" nastaveno na true, každá změna v payloadu obsahuje pole "data" s aktuálním stavem řádku. Použijte "columnsToSend" pro výběr konkrétních polí a relací. Eliminuje potřebu následného požadavku GET.

Příklady payloadu webhooku

Příklady payloadů webhooku, které váš koncový bod obdrží

Payload webhooku s jednou změnou [badge:Payload|info|right]

Příklad payloadu pro jednu změnu

{
    "hookId": "hook-123-456",
    "tenantId": "tenant-789",
    "organisationId": "org-101",
    "changeSetId": null,
    "changes": [
        {
            "id": "change-001",
            "entity": "products",
            "operation": "update",
            "rowId": "product-456",
            "changeSetId": null
        }
    ],
    "timestamp": "2025-09-08T10:30:00.000Z"
}

Payload webhooku s dávkovými změnami [badge:Payload|info|right]

Příklad payloadu s více změnami (až 100)

{
    "hookId": "hook-123-456",
    "tenantId": "tenant-789",
    "organisationId": "org-101",
    "changeSetId": "changeset-abc",
    "changes": [
        {
            "id": "change-001",
            "entity": "products",
            "operation": "create",
            "rowId": "product-456",
            "changeSetId": "changeset-abc"
        },
        {
            "id": "change-002",
            "entity": "products",
            "operation": "update",
            "rowId": "product-457",
            "changeSetId": "changeset-abc"
        },
        {
            "id": "change-003",
            "entity": "categories",
            "operation": "update",
            "rowId": "category-123",
            "changeSetId": "changeset-abc"
        }
    ],
    "timestamp": "2025-09-08T10:30:00.000Z"
}

Příklad Payload Webhooku [badge:Payload|info|right]

Když je na webhooku nastaveno sendPayload: true, každá položka změny obsahuje pole data s aktuálním stavem řádku v době doručení. To eliminuje potřebu, aby váš příjemce prováděl následný požadavek GET.

Jednoduchý payload (bez columnsToSend — celý záznam):

{
    "hookId": "hook-123-456",
    "tenantId": "tenant-789",
    "organisationId": "org-101",
    "changeSetId": null,
    "changes": [
        {
            "id": 10042,
            "entity": "products",
            "operation": "update",
            "rowId": "product-456",
            "changeSetId": null,
            "data": {
                "id": "product-456",
                "name": "Wireless Headphones",
                "code": "WH-1000",
                "price": 149.99,
                "status": "active",
                "inventory_count": 42,
                "category_id": "cat-electronics",
                "updatedAt": "2025-09-08T10:29:58.000Z"
            }
        }
    ],
    "timestamp": "2025-09-08T10:30:00.000Z"
}

S columnsToSend — jsou zahrnuta pouze vybraná pole; relace jsou rozšířeny přímo:

{
    "hookId": "hook-123-456",
    "tenantId": "tenant-789",
    "organisationId": "org-101",
    "changeSetId": null,
    "changes": [
        {
            "id": 10042,
            "entity": "products",
            "operation": "update",
            "rowId": "product-456",
            "changeSetId": null,
            "data": {
                "id": "product-456",
                "name": "Wireless Headphones",
                "price": 149.99,
                "status": "active",
                "category": {
                    "id": "cat-electronics",
                    "name": "Electronics"
                }
            }
        }
    ],
    "timestamp": "2025-09-08T10:30:00.000Z"
}

Pro dávku s více změnami nese každá položka svá vlastní data:

{
    "hookId": "hook-123-456",
    "tenantId": "tenant-789",
    "organisationId": "org-101",
    "changeSetId": "changeset-abc",
    "changes": [
        {
            "id": 10050,
            "entity": "products",
            "operation": "create",
            "rowId": "product-500",
            "changeSetId": "changeset-abc",
            "data": {
                "id": "product-500",
                "name": "Smart Watch Pro",
                "code": "SW-PRO",
                "price": 299.00,
                "status": "active",
                "inventory_count": 10,
                "category_id": "cat-electronics",
                "updatedAt": "2025-09-08T10:29:59.000Z"
            }
        },
        {
            "id": 10051,
            "entity": "products",
            "operation": "update",
            "rowId": "product-456",
            "changeSetId": "changeset-abc",
            "data": {
                "id": "product-456",
                "name": "Wireless Headphones",
                "code": "WH-1000",
                "price": 129.99,
                "status": "active",
                "inventory_count": 41,
                "category_id": "cat-electronics",
                "updatedAt": "2025-09-08T10:29:59.000Z"
            }
        }
    ],
    "timestamp": "2025-09-08T10:30:00.000Z"
}

**Kdy použít sendPayload**
- Váš příjemce potřebuje data záznamu okamžitě bez následného požadavku GET
- Synchronizujete data do externího datového skladu nebo vyhledávacího indexu a potřebujete kompletní dokument
- Chcete se vyhnout souběžným stavům, kdy druhá změna dorazí dříve, než stihnete záznam načíst

**Použijte columnsToSend k řízení struktury `data`**
- Ponechte `columnsToSend` prázdné pro příjem celého plochého záznamu
- Nastavte `columnsToSend` na konkrétní klíče polí pro příjem pouze těchto polí
- Zahrňte cesty k tečkovaným relacím (např. `category.name`), aby se relace rozšířily přímo

**Kdy NEPOUŽÍVAT sendPayload**
- Zajímá vás pouze *které* záznamy se změnily, nikoli jejich aktuální stav (udržuje payload menší)
- Entita má velmi velké záznamy – použijte `columnsToSend` k omezení struktury
- Záznam může být v době doručení smazán; pro operace `delete` bude `data` `undefined` (řádek již neexistuje)

Mechanismus opakování a zpoždění

Spolehlivé doručování se strategií exponenciálního zpoždění

card: Počáteční zpoždění opakování
icon: clock
1 minuta zpoždění po prvním selhání. Když webhook selže, první opakování proběhne po 1 minutě.
card: Exponenciální zpoždění
icon: refresh-cw
Progresivní zpoždění se zvyšuje. Zpoždění opakování: 1 min → 3 min → 9 min → 27 min → 81 min → konečné selhání.
card: Maximální počet pokusů
icon: alert-triangle
5 pokusů o opakování na webhook. Po 5 neúspěšných pokusech je webhook odstraněn z fronty a použije se 1hodinové zpoždění.
card: Reset při úspěchu
icon: check-circle
Počet opakování se resetuje při úspěchu. Když je webhook úspěšný, zpoždění opakování a počet selhání se resetují na nulu.

**Plán opakování**
- **1. selhání:** Opakování za 1 minutu
- **2. selhání:** Opakování za 3 minuty
- **3. selhání:** Opakování za 9 minut
- **4. selhání:** Opakování za 27 minut
- **5. selhání:** Opakování za 81 minut
- **Konečné selhání:** Odstranit z fronty, použít 1hodinovou penalizaci

Doporučené postupy

Požadavky na koncový bod

  • Vracejte stavové kódy HTTP 200-299 pro úspěšné zpracování
  • Odpovězte do 120 sekund (časový limit požadavku)
  • Používejte koncové body HTTPS pro zabezpečení
  • Implementujte idempotenci pro zpracování duplicitních doručení

Zpracování chyb

  • Vracejte stavové kódy 4xx pro trvalá selhání (bez opakování)
  • Vracejte stavové kódy 5xx pro dočasná selhání (bude se opakovat)
  • Protokolujte payloady webhooku pro ladění neúspěšných doručení
  • Implementujte elegantní degradaci pro dočasné výpadky

Doporučené postupy filtrování

  • Používejte specifické filtry entity pro snížení zbytečných volání webhooku
  • Implementujte filtry where pro příjem pouze relevantních změn
  • Používejte filtry sloupců pro spuštění webhooků pouze při změně důležitých polí
  • Zvažte použití allowInChangeSet: false pro jednodušší zpracování

Tipy pro výkon

  • Zpracovávejte payloady webhooku asynchronně, pokud je to možné
  • Kombinujte více možností filtrování pro přesné cílení webhooku
  • Monitorujte míru selhání webhooku a upravte filtry podle toho
  • Používejte filtry sloupců, abyste se vyhnuli webhookům pouze při aktualizacích časového razítka