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

Čo je to?

Poznámka správcu: Toto je “systém upozornení”, ktorý proaktívne odosiela aktualizácie z vášho {productName} do vašich ďalších aplikácií v momente, keď sa stanú. Namiesto toho, aby sa vaše ďalšie systémy pýtali “Je tu niečo nové?”, náš systém im zavolá a povie “Hej, tu je to, čo sa práve zmenilo!”

Pre koho je to určené? Administrátori by si to mali prečítať, aby pochopili, ako povoliť automatizáciu v reálnom čase vo svojom podnikaní. Aj keď môžete vidieť aktívne webhooks vo svojich nastaveniach, technické nastavenie (URL a spracovanie payloadu) musí vykonať vývojár, ktorý dokáže vytvoriť “listener” pre tieto notifikácie.

Kľúčové výhody pre e-shop:

  • Okamžité aktualizácie: Udržujte svoje nástroje pre sklad, prepravu alebo CRM aktualizované v priebehu niekoľkých sekúnd od novej objednávky alebo zmeny zásob.
  • Inteligentné filtrovanie: Posielajte upozornenia iba na veci, na ktorých záleží (napr. “informujte ma iba o nových objednávkach” alebo “informujte ma iba o zmene ceny produktu”).
  • Spoľahlivé doručovanie: Ak je váš ďalší systém dočasne mimo prevádzky, náš systém sa bude snažiť odoslať notifikáciu, kým sa mu to nepodarí.
  • Efektívna automatizácia: Odosielaním údajov iba vtedy, keď sa zmenia, ušetríte náklady na server a zabezpečíte, že vaše integrácie budú čo najrýchlejšie.

Prehľad

Webhooks umožňujú vašej aplikácii prijímať notifikácie v reálnom čase, keď dôjde k zmenám údajov v systéme. Sú ideálne na udržiavanie synchronizácie externých systémov s vašimi údajmi.

**Kľúčové vlastnosti**
- Dávkové doručovanie: Zmeny sa zhromažďujú po dobu 5 sekúnd a odosielajú sa v dávkach (až 100 zmien)
- Pokročilé filtrovanie: Filtrovanie na základe entity, poľa a stĺpca
- Spoľahlivé doručovanie: Automatické opakovanie s exponenciálnym backoff (1min → 3min → 9min → 27min → 81min)
- Zoskupovanie ChangeSet: Zmeny sú zoskupené podľa changeSet pre transakčnú konzistenciu

Ako to funguje

1. Zmeny údajov

Keď dôjde k zmenám údajov (operácie create, update, delete), systém tieto zmeny zachytí.

2. 5-sekundové dávkovacie okno

Zmeny sa zhromažďujú po dobu 5 sekúnd po prvej zmene, aby sa vytvorili efektívne dávky.

3. Filtrovanie a zoskupovanie

Zmeny sa filtrujú na základe konfigurácie webhooku (entita, where, stĺpce) a zoskupujú sa podľa changeSet pre konzistenciu.

4. HTTP POST doručovanie

Payload webhooku sa odosiela ako HTTP POST do vášho endpointu s až 100 zmenami na požiadavku.

Príklady registrácie Webhooku

Zistite, ako registrovať webhooks s rôznymi konfiguráciami

Registrácia základného Webhooku

Vytvorte webhook pre zmeny 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 filtrom entity

Prijímajte webhooks iba pre konkrétne 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 filtrom Where

Filtrujte zmeny na základe hodnôt 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 filtrom stĺpcov

Spustite webhook iba pri zmene konkrétnych stĺpcov [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 pre všetky entity

Prijímajte notifikácie pre všetky zmeny 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 ovládaním ChangeSet

Ovládajte, či sa majú zahrnúť zmeny v rámci changeSets [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 dátovej časti

Vložte aktuálny stav každého zmeneného záznamu priamo do dátovej časti [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 kombinovať s akýmikoľvek inými možnosťami filtra:

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

Presne určte, ktoré polia (a súvisiace dáta) sú zahrnuté v dátovej časti data [badge:Advanced|info|right]

Keď je nastavené columnsToSend, systém ho použije ako dotaz na výber stĺpcov — môže zahŕňať rozšírenia vzťahov. Ak je columnsToSend prázdne (alebo vynechané), vráti sa 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"]
}

Funkcie filtrovania

Ovládajte, ktoré zmeny spúšťajú vaše webhooks

card: Filter entít
icon: filter
Filtrujte podľa konkrétneho typu entity. Nastavte pole "entity" na prijímanie webhooks iba pre konkrétne entity, ako napríklad "products", "units" atď. Použite null na prijímanie všetkých zmien entity.
card: Filter Where
icon: code
Pokročilé filtrovanie na základe polí. Použite where klauzuly podobné SQL na filtrovanie zmien na základe hodnôt polí. Príklad: "price > 100 AND status = 'active'"
card: Filter stĺpcov
icon: filter
Filtrujte podľa konkrétnych zmien stĺpcov. Použite pole "columns" na spustenie webhooks iba vtedy, keď sa skutočne zmenili konkrétne stĺpce. Príklad: ["price", "status", "inventory_count"]
card: Ovládanie Sady zmien
icon: play
Zahrňte alebo vylúčte údaje sady zmien. Ovládajte, či sa majú zahrnúť zmeny v rámci sád zmien pomocou poľa "allowInChangeSet" (true/false).
card: Doručenie dátovej časti
icon: database
Vložte aktuálny stav záznamu do každého záznamu zmeny. Keď je "sendPayload" nastavené na true, každá zmena v dátovej časti obsahuje pole "data" s aktuálnym stavom riadku. Použite "columnsToSend" na výber konkrétnych polí a vzťahov. Eliminuje potrebu následnej požiadavky GET.

Príklady payloadu Webhooku

Príklady payloadov webhooku, ktoré váš endpoint prijme

Payload Webhooku s jednou zmenou [badge:Payload|info|right]

Príklad payloadu pre jednu zmenu

{
    "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 zmenami [badge:Payload|info|right]

Príklad payloadu s viacerými zmenami (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"
}

Príklad Webhooku s dátovou časťou [badge:Payload|info|right]

Keď je na háčiku nastavené sendPayload: true, každý záznam zmeny obsahuje pole data s aktuálnym stavom riadku v čase doručenia. To eliminuje potrebu, aby váš prijímač vykonával následnú požiadavku GET.

Jednoduchá dátová časť (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 — sú zahrnuté iba vybrané polia; vzťahy sú rozšírené priamo:

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

Pre dávku s viacerými zmenami, každý záznam nesie svoje 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"
}

**Kedy použiť sendPayload**
- Váš prijímač potrebuje dáta záznamu okamžite bez následnej požiadavky GET
- Synchronizujete dáta do externého dátového skladu alebo vyhľadávacieho indexu a potrebujete kompletný dokument
- Chcete sa vyhnúť pretekovým podmienkam, kedy druhá zmena príde skôr, ako stihnete načítať záznam

**Použite columnsToSend na ovládanie štruktúry `data`**
- Nechajte `columnsToSend` prázdne, aby ste dostali celý plochý záznam
- Nastavte `columnsToSend` na konkrétne kľúče polí, aby ste dostali iba tieto polia
- Zahrňte cesty vzťahov s bodkami (napr. `category.name`), aby sa vzťahy rozšírili priamo

**Kedy NEPOUŽÍVAŤ sendPayload**
- Záleží vám len na tom, *ktoré* záznamy sa zmenili, nie na ich aktuálnom stave (udržuje menšiu dátovú časť)
- Entita má veľmi veľké záznamy — použite `columnsToSend` na obmedzenie štruktúry
- Záznam môže byť v čase doručenia vymazaný; pre operácie `delete` bude `data` `undefined` (riadok už neexistuje)

Mechanizmus opakovania a Backoff

Spoľahlivé doručovanie so stratégiou exponenciálneho backoff

card: Počiatočné oneskorenie opakovania
icon: clock
1 minúta oneskorenie po prvom zlyhaní. Keď webhook zlyhá, prvé opakovanie sa uskutoční po 1 minúte.
card: Exponenciálny Backoff
icon: refresh-cw
Progresívne oneskorenie sa zvyšuje. Oneskorenia opakovania: 1 min → 3 min → 9 min → 27 min → 81 min → konečné zlyhanie.
card: Maximálny počet pokusov
icon: alert-triangle
5 pokusov o opakovanie na webhook. Po 5 neúspešných pokusoch sa webhook odstráni z frontu a použije sa 1-hodinové oneskorenie.
card: Reset úspechu
icon: check-circle
Počet opakovaní sa resetuje pri úspechu. Keď je webhook úspešný, oneskorenie opakovania a počet zlyhaní sa resetujú na nulu.

**Plán opakovania**
- **1. zlyhanie:** Opakovanie o 1 minútu
- **2. zlyhanie:** Opakovanie o 3 minúty
- **3. zlyhanie:** Opakovanie o 9 minút
- **4. zlyhanie:** Opakovanie o 27 minút
- **5. zlyhanie:** Opakovanie o 81 minút
- **Konečné zlyhanie:** Odstrániť z frontu, použiť 1-hodinovú penalizáciu

Osvedčené postupy

Požiadavky na Endpoint

  • Vráťte stavové kódy HTTP 200-299 pre úspešné spracovanie
  • Odpovedzte do 120 sekúnd (časový limit požiadavky)
  • Používajte HTTPS endpointy pre bezpečnosť
  • Implementujte idempotenciu na spracovanie duplicitných doručení

Spracovanie chýb

  • Vráťte stavové kódy 4xx pre trvalé zlyhania (žiadne opakovanie)
  • Vráťte stavové kódy 5xx pre dočasné zlyhania (bude sa opakovať)
  • Zaznamenávajte payloady webhooku na ladenie neúspešných doručení
  • Implementujte elegantnú degradáciu pre dočasné výpadky

Osvedčené postupy filtrovania

  • Používajte špecifické filtre entity na zníženie zbytočných volaní webhooku
  • Implementujte where filtre na prijímanie iba relevantných zmien
  • Používajte filtre stĺpcov na spustenie webhooks iba pri zmene dôležitých polí
  • Zvážte použitie allowInChangeSet: false pre jednoduchšie spracovanie

Tipy pre výkon

  • Spracovávajte payloady webhooku asynchrónne, keď je to možné
  • Kombinujte viacero možností filtrovania pre presné zacielenie webhooku
  • Monitorujte mieru zlyhania webhooku a podľa toho upravte filtre
  • Používajte filtre stĺpcov, aby ste sa vyhli webhookom pri aktualizáciách iba s časovou pečiatkou