События: обзор методов и событий

События в Битрикс24 — это уведомления об изменениях данных, например, о создании сделки или удалении товара. Когда приложение или вебхук подписывается на событие, Битрикс24 начинает отправлять ему такие уведомления. Чтобы получать события, настройте обработчик.

Обработчик события — это внешний URL-адрес, на который Битрикс24 отправляет POST-запрос с данными об изменении. Обработчик позволяет:

• синхронизировать данные с внешней системой
• запускать автоматические сценарии
• проверять данные по правилам бизнес-логики

Быстрый переход: все методы и события

Как работают событияКак работают события

1. Приложение регистрирует обработчик для нужного события методом event.bind, а исходящий вебхук — в интерфейсе Битрикс24.
2. Пользователь совершает действие в Битрикс24, например, изменяет задачу.
3. Битрикс24 отправляет уведомление на URL обработчика через сервер очередей.

Особенности работыОсобенности работы

Битрикс24 не вызывает обработчик напрямую. Сначала событие попадает в очередь на специальном сервере. Оттуда на ваш обработчик уходит POST-запрос. Из-за этого запрос может прийти с небольшой задержкой.

Сервер проверяет скорость ответа обработчика. Если обработчик отвечает медленно, сервер снижает частоту вызовов. Интервалы между запросами увеличиваются.

Актуальные адреса сервера очередей.

Как подписаться на событиеКак подписаться на событие

Подписаться на событие можно двумя способами.

Метод event.bind работает только в контексте авторизации приложения. Список событий, доступных приложению, возвращает метод events.

Подписка через исходящий вебхукПодписка через исходящий вебхук

1. В Битрикс24 откройте раздел Разработчикам > Другое > Исходящий вебхук.
2. Укажите URL обработчика.
3. Выберите одно или несколько событий из списка, например OnCrmDealAdd.
4. Сохраните вебхук. Поле Токен приложения сгенерируется автоматически.

Проверить, что события доходят до вашего обработчика, поможет статья Как проверить свой обработчик для обработки событий Битрикс24.

Что приходит в обработчикЧто приходит в обработчик

Битрикс24 отправляет запрос с content-type application/x-www-form-urlencoded. В примерах ниже структура показана в формате JSON. При передаче все значения приходят строками.

{
    "event": "ONCRMDEALADD",
    "event_handler_id": "185",
    "data": {
        "FIELDS": {
            "ID": "7405"
        }
    },
    "ts": "1766047124",
    "auth": {
        "access_token": "s6p6eclrvim6da22ft9ch94ekreb52lv",
        "expires_in": "3600",
        "scope": "crm",
        "domain": "some-domain.bitrix24.ru",
        "server_endpoint": "https://oauth.bitrix24.tech/rest/",
        "status": "L",
        "client_endpoint": "https://some-domain.bitrix24.ru/rest/",
        "member_id": "d897063e1ce7c5eb9f04b9751eef5915",
        "application_token": "51856fefc120afa4b628cc82d3935cce"
    }
}

{
    "event": "ONCRMDEALADD",
    "event_handler_id": "975",
    "data": {
        "FIELDS": {
            "ID": "7405"
        }
    },
    "ts": "1766047124",
    "auth": {
        "domain": "some-domain.bitrix24.ru",
        "client_endpoint": "https://some-domain.bitrix24.ru/rest/",
        "server_endpoint": "https://oauth.bitrix24.tech/rest/",
        "member_id": "d897063e1ce7c5eb9f04b9751eef5915",
        "application_token": "jvh9y1ulvt2m6k5or90v9mg8nn32ozas"
    }
}

Состав ключей верхнего уровня одинаковый для всех событий.

Событие сообщает только о факте изменения. Чтобы получить сами данные объекта, вызовите метод чтения этого объекта, например crm.deal.get.

Параметр authПараметр auth

Токены OAuth 2.0 выдаются от имени пользователя, указанного при подписке, и наследуют его права. Какой это пользователь, зависит от параметра auth_type метода event.bind.

Состав ключей auth зависит от способа подписки. В исходящий вебхук приходят только domain, client_endpoint, server_endpoint, member_id и application_token — токены OAuth 2.0 и данные приложения вебхуку не передаются.

Токен refresh_token приходит не со всеми событиями. Его передают только события, которым нужен долгий доступ к Битрикс24, например OnAppInstall и onOfflineEvent.

Ключ application_token — основной способ убедиться, что запрос пришел от Битрикс24. Как проверять его в коде обработчика, описано в статье Безопасность в обработчиках.

Обязательные параметры отмечены *

Ограничения событийОграничения событий

У событий есть два основных ограничения:

1. Нельзя регулировать нагрузку. При массовом изменении данных вы получите много вызовов подряд. Если в Битрикс24 одновременно изменили тысячу сделок, обработчик получит тысячу вызовов.
2. Повторных отправок нет. Если ваш сервер не ответил или вернул ошибку, сервер очередей Битрикс24 зафиксирует сбой, но не отправит событие повторно.

Если важно обработать все события без потерь, используйте офлайн-события. Они позволяют получить события из очереди вручную.

Права доступаПрава доступа

Обычный пользователь может регистрировать, получать и удалять свои обработчики онлайн-событий методами event.bind, event.get и event.unbind. Если в event.bind указать auth_type другого пользователя, метод вернет ошибку доступа. Ограничения auth_type в event.unbind описаны на странице метода.

С очередью офлайн-событий может работать только администратор. Это ограничение действует для методов event.offline.get, event.offline.list, event.offline.clear и event.offline.error.

Типовые ошибки методов event.*Типовые ошибки методов event.*

Полный список ошибок приведен на странице каждого метода.

Обзор методов и событийОбзор методов и событий

Scope: базовый

Кто может выполнять метод: зависит от метода

Продолжите изучениеПродолжите изучение

• Как проверить свой обработчик для обработки событий Битрикс24
• Безопасность в обработчиках
• Офлайн-события
• Необходимые сетевые доступы