Prehľad webhookov

Sursa zaznamená udalosť pri každej dôležitej zmene: karta sa zverejní, overí alebo archivuje, niekto si prečíta oznámenie, otázka zostane bez odpovede. Udalosti môžete prijímať dvoma spôsobmi a oba používať súčasne:

	Webhooky	Kanál udalostí
Ako	Sursa pošle každú udalosť na vašu adresu HTTPS hneď, ako nastane.	Čítate `GET /v1/webhook-events`, kedy chcete.
Oneskorenie	Sekundy.	Také časté, ako často sa dopytujete.
Potrebujete	Verejného príjemcu s HTTPS.	Len kľúč API s rolou `admin` a rozsahom `webhooks:manage`.
Vhodné na	Reakcie na zmeny: upozornenie, synchronizácia, spustenie workflow.	Dávkové úlohy, dobiehanie po výpadku, zosúladenie.

Oba spôsoby prinášajú tie isté udalosti s rovnakými ID. Každá udalosť sa v kanáli uchováva 30 dní bez ohľadu na to, či ju odoberal nejaký webhook.

Udalosť

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

Pole	Význam
`id`	ID udalosti, `evt_` a 32 šestnástkových znakov. Rovnaké pri každom pokuse o doručenie aj v kanáli.
`type`	Čo sa stalo, v tvare `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kedy zmena nastala, v UTC.
`api_version`	Verzia API, ktorej schému `data` dodržiava.
`object`	Typ a ID objektu, ktorého sa udalosť týka.
`data`	Podrobnosti. Ich tvar závisí od typu a je opísaný v katalógu udalostí.
`data.previous_attributes`	V udalostiach `*.updated`: predchádzajúce hodnoty polí, ktoré sa zmenili.
`sequence`, `payload`, `test`	Len v doručeniach webhookov: poradie v rámci webhooku, režim obsahu a či ide o testovaciu udalosť.

data obsahuje len to, čo by cez API videl ktorýkoľvek čitateľ objektu. Nikdy neobsahuje zoznamy prístupov, oprávnenia iných ľudí ani skryté polia. Dôvody v udalostiach sú krátke neutrálne kódy, napríklad no_hits, restricted alebo index_failed.

Typy udalostí

Udalosti pokrývajú tieto oblasti:

Oblasť	Príklady
Karty	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Overenie	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Štruktúra	`collection.created`, `folder.updated`
Spolupráca	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Odpovede	`question.unanswered`, `question.feedback_created`, `access_request.created`
Ľudia a prístup	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Zdroje a import	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Úlohy	`job.completed`, `job.failed`, `export.ready`
Webhooky	`webhook.endpoint_disabled`, `webhook.ping`

Úplný zoznam so schémou a ukážkou každej udalosti nájdete v katalógu udalostí v referencii API. GET /v1/webhooks/catalog vráti typy dostupné vo vašej inštalácii.

Postupne pribúdajú nové typy udalostí a existujúce udalosti dostávajú nové polia. Typy udalostí sa nikdy nepremenujú ani neodstránia. Váš príjemca musí preskočiť typy a polia, ktoré nepozná.

Kto čo dostáva

Webhook dostane udalosť len vtedy, ak objekt udalosti vidí, rovnako ako kľúč API: podľa svojej roly, dátového profilu a kolekcií. Webhook obmedzený na kolekciu support nikdy nedostane udalosti o kartách vo finance. Udalosti o ľuďoch, kľúčoch, zdrojoch, importoch, úlohách, exportoch, fakturácii, aplikáciách a samotných webhookoch idú len webhookom s rolou admin.

V rámci toho si každý webhook vyberá svoje udalosti:

podľa typu pomocou masiek: card.* pre každú udalosť karty, * pre každú udalosť;
podľa kolekcie a štítku pri udalostiach kariet.

Režim obsahu webhooku je full (udalosť s data, predvolené) alebo thin (udalosť bez data: váš príjemca si objekt načíta cez API vlastným kľúčom a vždy vidí jeho aktuálny stav).

Doručovanie v skratke

POST cez HTTPS s udalosťou vo formáte JSON, podpísaný tajným kľúčom webhooku v dvoch formátoch: Standard Webhooks (webhook-signature) a staršom X-KB-Signature.
Každá odpoveď 2xx do 10 sekúnd je úspech.
Neúspešné doručenie sa opakuje takmer tri dni s rastúcimi prestávkami. Retry-After v odpovedi 429 alebo 503 sa rešpektuje; 410 webhook vypne; 10 zlyhaní za sebou ho pozastaví, kým sa znova neobnoví.
Doručenia na jeden webhook sa posielajú prísne v poradí. Pomalý webhook nezdržiava ostatné webhooky.
Tá istá udalosť môže prísť viac ako raz: duplicity vyraďte podľa webhook-id.

Návod Prijímajte webhooky prevedie celým príjemcom vrátane overenia podpisu v Node.js, Pythone a Go.

Správa webhookov

Úloha	Operácia
Vytvoriť webhook a získať jeho tajný kľúč	`POST /v1/webhooks`
Zmeniť adresu, udalosti alebo stav	`PATCH /v1/webhooks/{webhook_id}`
Odoslať testovaciu udalosť	`POST /v1/webhooks/{webhook_id}/test`
Vymeniť tajný kľúč	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Obnoviť pozastavený webhook	`POST /v1/webhooks/{webhook_id}/resume`
Zobraziť doručenia a odpovede	`GET /v1/webhooks/{webhook_id}/deliveries`
Odoslať doručenie znova	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Na správu webhookov treba kľúč s rolou admin a rozsahom webhooks:manage alebo administrátora v administrátorskom rozhraní. Organizácia môže mať najviac 20 webhookov. Webhooky sú súčasťou tarify organizácie; bez nich tieto operácie odpovedajú 403 s kódom webhooks.feature_disabled.