Dokumentace k Webhookům

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
}

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).

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"
}

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