Přehled webhooků

Sursa zaznamenává událost při každé důležité změně: karta je publikována, ověřena nebo archivována, oznámení je přečteno, otázka zůstane bez odpovědi. Události můžete přijímat dvěma způsoby a používat oba současně:

	Webhooky	Kanál událostí
Jak	Sursa posílá každou událost na vaši adresu HTTPS v okamžiku, kdy nastane.	Čtete `GET /v1/webhook-events`, kdy chcete.
Zpoždění	Sekundy.	Podle toho, jak často se dotazujete.
Potřebujete	Veřejného příjemce na HTTPS.	Jen klíč API s rolí `admin` a rozsahem `webhooks:manage`.
Vhodné pro	Reakce na změny: upozornění, synchronizace, spuštění workflow.	Dávkové úlohy, dohnání zpoždění po výpadku, sesouhlasení.

Obojí nese stejné události se stejnými ID. Každá událost zůstává v kanálu 30 dní bez ohledu na to, zda ji odebíral nějaký webhook.

Událost

{
  "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 události, `evt_` a 32 šestnáctkových znaků. Stejné při každém pokusu o doručení i v kanálu.
`type`	Co se stalo, ve tvaru `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Kdy změna nastala, v UTC.
`api_version`	Verze API, jejímuž schématu odpovídá `data`.
`object`	Typ a ID objektu, kterého se událost týká.
`data`	Podrobnosti. Jeho tvar závisí na typu a je popsán v katalogu událostí.
`data.previous_attributes`	V událostech `*.updated`: dřívější hodnoty polí, která se změnila.
`sequence`, `payload`, `test`	Jen v doručeních webhooků: pozice v pořadí webhooku, režim obsahu a zda jde o testovací událost.

data obsahuje jen to, co by přes API viděl kterýkoli čtenář objektu. Nikdy neobsahuje seznamy přístupů, oprávnění jiných lidí ani skrytá pole. Důvody v událostech jsou krátké neutrální kódy, například no_hits, restricted nebo index_failed.

Typy událostí

Události pokrývají tyto oblasti:

Oblast	Příklady
Karty	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Ověření	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktura	`collection.created`, `folder.updated`
Spolupráce	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Odpovědi	`question.unanswered`, `question.feedback_created`, `access_request.created`
Lidé a pří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ý seznam se schématem a ukázkou každé události je v katalogu událostí v referenci API. GET /v1/webhooks/catalog vrací typy dostupné ve vaší instalaci.

Postupně přibývají nové typy událostí a stávající události získávají nová pole. Typy událostí se nikdy nepřejmenovávají ani neodstraňují. Váš příjemce musí přeskakovat typy a pole, které nezná.

Kdo co dostává

Webhook dostane událost jen tehdy, když objekt události vidí, stejně jako klíč API: podle své role, datového profilu a kolekcí. Webhook omezený na kolekci support nikdy nedostane události o kartách ve finance. Události o lidech, klíčích, zdrojích, importech, úlohách, exportech, fakturaci, aplikacích a události samotných webhooků dostávají jen webhooky s rolí admin.

V těchto mezích si každý webhook vybírá své události:

podle typu, pomocí masek: card.* pro všechny události karet, * pro všechny události;
podle kolekce a štítku u událostí karet.

Režim obsahu webhooku je full (událost s data, výchozí) nebo thin (událost bez data: váš příjemce si objekt přečte přes API vlastním klíčem a vždy vidí jeho aktuální stav).

Doručování v kostce

POST přes HTTPS s událostí ve formátu JSON, podepsaný tajným klíčem webhooku ve dvou formátech: Standard Webhooks (webhook-signature) a dřívější X-KB-Signature.
Jakákoli odpověď 2xx do 10 sekund je úspěch.
Neúspěšné doručení se opakuje téměř tři dny s rostoucími pauzami. Retry-After v odpovědi 429 nebo 503 se respektuje; 410 webhook vypne; 10 neúspěchů za sebou ho pozastaví, dokud se znovu neobnoví.
Doručení na jeden webhook se odesílají přísně v pořadí. Pomalý webhook nezdržuje ostatní webhooky.
Stejná událost může dorazit víckrát: duplicity zahazujte podle webhook-id.

Návod Příjem webhooků prochází úplného příjemce s ověřením podpisu v Node.js, Pythonu a Go.

Správa webhooků

Co chcete udělat	Operace
Vytvořit webhook a získat jeho tajný klíč	`POST /v1/webhooks`
Změnit adresu, události nebo stav	`PATCH /v1/webhooks/{webhook_id}`
Odeslat testovací událost	`POST /v1/webhooks/{webhook_id}/test`
Obměnit tajný klíč	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Obnovit pozastavený webhook	`POST /v1/webhooks/{webhook_id}/resume`
Zobrazit doručení a odpovědi	`GET /v1/webhooks/{webhook_id}/deliveries`
Odeslat doručení znovu	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Správa webhooků vyžaduje klíč s rolí admin a rozsahem webhooks:manage nebo administrátora v administračním rozhraní. Organizace může mít až 20 webhooků. Webhooky jsou součástí tarifu organizace; bez nich tyto operace odpovídají 403 s kódem webhooks.feature_disabled.