Каталог событий

Форма данных

Каждое событие - это один JSON-объект:

{
  "id": "evt_01HKQN9…",
  "type": "conversation.created",
  "occurred_at": "2026-04-20T14:23:45.123Z",
  "account_id": "7c1d2c6e-…",
  "site_id": "0f3a…",
  "data": { … the resource, in the same shape the API returns it … }
}

id - это значение из заголовка X-RolChat-Event-Id, оно не меняется между повторами. type имеет вид <domain>.<noun>.<verb> или <domain>.<verb> в snake_case. data содержит ресурс в том виде, в каком его вернул бы соответствующий эндпоинт GET, поэтому приёмник можно писать по справочнику API без отдельной схемы.

Семейства событий

Семейство	Примеры	Когда отправляется
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Диалог меняет состояние или ответственного
message.*	message.created, message.delivered, message.read, message.failed	Публикуется сообщение или меняется статус его доставки
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Меняется лид, контакт, компания или сделка
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Меняется тикет
visitor.*	visitor.identified, visitor.cobrowse.requested	Посетитель идентифицирован или запрашивает сеанс совместного просмотра
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Формы, бронирования, кампании
kb.*	kb.article.published, kb.article.unpublished	Изменения в базе знаний
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Звонки и голосовая почта
automation.*	automation.rule.executed, automation.rule.failed	Выполняется правило автоматизации
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Согласия и запросы субъектов данных
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Подписка и счета
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Важные для безопасности события аккаунта
ai.*	ai.usage.recorded	Каждый вызов ИИ-адаптера, с количеством токенов

Точный список растёт вместе с продуктом; экран подписки показывает все типы, которые может получать ваш аккаунт, и позволяет фильтровать по типу.

Подписка

Подписки на вебхуки принадлежат плагину. В разделе Настройки → Плагины откройте плагин (или создайте собственный) и добавьте эндпоинт: HTTPS-адрес, нужные типы событий и, при желании, список разрешённых IP. Секрет для подписи показывается один раз. Доставки, повторы и недоставленные сообщения для этого эндпоинта отображаются в Журнале вебхуков плагина.

Протокол плагинов на странице Плагины описывает, как плагин объявляет нужные ему события в своём манифесте.

Порядок и доставка

• Доставка выполняется как минимум один раз. Дедуплицируйте по id.
• События одного ресурса отправляются по порядку, но повторы могут изменить порядок доставок. Опирайтесь на occurred_at и updated_at ресурса, а не на время получения.
• Подписка, которая постоянно завершается ошибкой, накапливает недоставленные сообщения; более 100 для одного эндпоинта вызывают оповещение на стороне RolChat и предупреждение в журнале плагина.