Обзор вебхуков

Sursa записывает событие о каждом важном изменении: карточку опубликовали, подтвердили или отправили в архив, объявление прочитали, вопрос остался без ответа. Получать события можно двумя способами и использовать оба сразу:

Оба способа передают одни и те же события с одними и теми же идентификаторами. Каждое событие хранится в ленте 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
}

В data есть только то, что любой читатель объекта мог бы увидеть через API. Там никогда не бывает списков доступа, прав других людей или скрытых полей. Причины в событиях — короткие нейтральные коды вроде no_hits, restricted или index_failed.

Типы событий

События охватывают такие области:

Полный список со схемой и примером каждого события — в каталоге событий справочника 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.

Управление вебхуками

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