Огляд вебхуків

Sursa записує подію для кожної важливої зміни: картку опубліковано, верифіковано чи архівовано, оголошення прочитано, запитання лишилося без відповіді. Отримувати події можна двома способами, і їх можна поєднувати:

	Вебхуки	Стрічка подій
Як	Sursa надсилає кожну подію на вашу адресу HTTPS у момент, коли вона стається.	Ви читаєте `GET /v1/webhook-events`, коли вам потрібно.
Затримка	Секунди.	Залежить від того, як часто ви опитуєте.
Що потрібно	Публічний отримувач HTTPS.	Лише ключ API з роллю `admin` та областю доступу `webhooks:manage`.
Для чого підходить	Реагувати на зміни: сповістити, синхронізувати, запустити робочий процес.	Пакетні завдання, надолуження після простою, звірка.

Обидва способи передають ті самі події з тими самими ідентифікаторами. Кожна подія зберігається в стрічці 30 днів — незалежно від того, чи був на неї підписаний якийсь вебхук.

Подія

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

Поле	Значення
`id`	ID події: `evt_` і 32 шістнадцяткові символи. Той самий у кожній спробі доставки та в стрічці.
`type`	Що сталося, у формі `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Коли сталася зміна, в UTC.
`api_version`	Версія API, схемі якої відповідає `data`.
`object`	Тип та ID об’єкта, якого стосується подія.
`data`	Подробиці. Їхня форма залежить від типу й описана в каталозі подій.
`data.previous_attributes`	У подіях `*.updated`: попередні значення полів, що змінилися.
`sequence`, `payload`, `test`	Лише в доставках вебхуків: місце в порядку доставок вебхука, режим вмісту та ознака тестової події.

data містить лише те, що будь-який читач об’єкта міг би побачити через API. У ньому ніколи немає списків доступу, дозволів інших людей чи прихованих полів. Причини в подіях — короткі нейтральні коди, як-от no_hits, restricted або index_failed.

Типи подій

Події охоплюють такі області:

Область	Приклади
Картки	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Верифікація	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Структура	`collection.created`, `folder.updated`
Співпраця	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Відповіді	`question.unanswered`, `question.feedback_created`, `access_request.created`
Люди й доступ	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Джерела та імпорт	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Завдання	`job.completed`, `job.failed`, `export.ready`
Вебхуки	`webhook.endpoint_disabled`, `webhook.ping`

Повний список зі схемою та прикладом кожної події наведено в каталозі подій довідника API. GET /v1/webhooks/catalog повертає типи, доступні у вашій інсталяції.

З часом додаються нові типи подій, а наявні події отримують нові поля. Типи подій ніколи не перейменовують і не видаляють. Ваш отримувач має пропускати невідомі типи й поля.

Хто що отримує

Вебхук отримує подію, лише якщо об’єкт події видимий для вебхука — так само, як для ключа API: за його роллю, профілем доступу та колекціями. Вебхук, обмежений колекцією support, ніколи не отримує подій про картки у finance. Події про людей, ключі, джерела, імпорт, завдання, експорт, оплату, застосунки й самі вебхуки надходять лише на вебхуки з роллю admin.

У цих межах кожен вебхук вибирає свої події:

за типом, за допомогою масок: card.* — для всіх подій карток, * — для всіх подій;
за колекцією й тегом — для подій карток.

Режим вмісту вебхука — full (подія з data, типово) або thin (подія без data: ваш отримувач читає об’єкт через API з власним ключем і завжди бачить його поточний стан).

Коротко про доставку

HTTPS-запит POST із подією у форматі JSON, підписаний секретом вебхука у двох форматах: Standard Webhooks (webhook-signature) і давнішому X-KB-Signature.
Будь-яка відповідь 2xx протягом 10 секунд означає успіх.
Невдала доставка повторюється впродовж майже трьох днів зі зростаючими паузами. Retry-After у відповіді 429 або 503 враховується; 410 вимикає вебхук; 10 невдач поспіль призупиняють його, доки роботу не відновлять.
Доставки на один вебхук надсилаються суворо по порядку. Повільний вебхук не затримує інших вебхуків.
Та сама подія може надійти кілька разів: відкидайте дублікати за webhook-id.

Посібник Отримуйте вебхуки крок за кроком описує повний отримувач із перевіркою підпису на Node.js, Python і Go.

Керування вебхуками

Завдання	Операція
Створити вебхук і отримати його секрет	`POST /v1/webhooks`
Змінити адресу, події чи стан	`PATCH /v1/webhooks/{webhook_id}`
Надіслати тестову подію	`POST /v1/webhooks/{webhook_id}/test`
Перевипустити секрет	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Відновити призупинений вебхук	`POST /v1/webhooks/{webhook_id}/resume`
Переглянути доставки й відповіді	`GET /v1/webhooks/{webhook_id}/deliveries`
Надіслати доставку знову	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Для керування вебхуками потрібен ключ із роллю admin та областю доступу webhooks:manage або адміністратор в інтерфейсі адміністратора. Організація може мати до 20 вебхуків. Вебхуки входять до тарифу організації; без них ці операції відповідають 403 з кодом webhooks.feature_disabled.