События (events) и офлайн-события

События (events) REST Битрикс24 позволяют получать уведомления об изменениях на портале — создании сделки, обновлении задачи, установке приложения — вместо постоянного опроса. Есть онлайн-события (портал сам шлёт POST на ваш URL) и офлайн-события (складываются в очередь, вы забираете их сами).

Зачем нужны события

Альтернатива событиям — периодический опрос (polling): интеграция раз в N секунд спрашивает портал «что изменилось?». Это дорого по лимитам и всегда с задержкой. События переворачивают модель: портал сам сообщает об изменении в момент, когда оно произошло.

Преимущества событийной модели:

• Реактивность. Уведомление приходит сразу после изменения.
• Экономия лимитов. Нет холостых опросов, когда ничего не менялось.
• Меньше нагрузки на портал и на вашу интеграцию.

Подписка через event.bind

Подписка регистрируется методом event.bind. Он принимает тип события и адрес обработчика:

event.bind?event=ONCRMDEALADD&handler=https://ваш-сервис.ru/handler.php

Сопутствующие методы:

• event.bind — подписаться на событие, указав обработчик.
• event.unbind — отписаться.
• event.get — получить список текущих подписок.
• events — получить перечень доступных типов событий.

Имена событий строятся по шаблону ON<МОДУЛЬ><ДЕЙСТВИЕ>: ONCRMDEALADD, ONCRMDEALUPDATE, ONTASKADD, ONCRMCONTACTDELETE, а также системные ONAPPINSTALL и ONAPPUNINSTALL.

Онлайн-события

Онлайн-событие срабатывает так: при изменении портал сразу отправляет POST-запрос на указанный handler. В теле приходят данные о событии — тип, ID изменённого объекта, отметка времени и токены.

Обработчик должен:

1. Быстро принять запрос и вернуть ответ (портал ждёт ответа ограниченное время).
2. Проверить подлинность запроса по application_token.
3. Поставить обработку в свою очередь, а не выполнять тяжёлую логику синхронно.

Офлайн-события и очередь

Офлайн-события не требуют постоянно доступного публичного URL. Портал складывает их в очередь, а интеграция забирает их, когда ей удобно. Это спасает, если ваш сервер временно недоступен или работает по расписанию.

Работа с очередью:

• event.offline.get — получить порцию накопленных событий из очереди.
• event.offline.clear — подтвердить обработку и удалить события из очереди по id процесса/сообщений.

Подписка на офлайн-режим задаётся при event.bind — в качестве обработчика указывается офлайн-режим вместо URL. После получения событий их обязательно подтверждают через event.offline.clear, иначе они вернутся при следующем чтении.

Онлайн против офлайн

Онлайн — для реального времени с надёжным публичным сервисом. Офлайн — для фоновых интеграций, серверов за NAT и сценариев с периодической обработкой.

Безопасность и надёжность

Обработчик событий открыт наружу, поэтому его нужно защищать:

• Проверяйте application_token из тела запроса — он подтверждает, что событие пришло от вашего портала, а не подделано.
• Обеспечьте идемпотентность. Одно и то же событие может прийти повторно; повторная обработка не должна ломать данные.
• Учитывайте порядок. События могут прийти не строго в хронологии — опирайтесь на данные объекта, а не только на факт события.
• Логируйте входящие события для разбора инцидентов.

Событие несёт минимум данных (обычно тип и ID). Актуальное состояние объекта дочитывайте отдельным REST-запросом — так вы избежите работы с устаревшими данными.

Итог

События REST Битрикс24 заменяют дорогой опрос реактивной моделью. Подписка идёт через event.bind, онлайн-события летят POST на ваш URL, офлайн-события копятся в очереди и забираются через event.offline.get с подтверждением event.offline.clear. Обязательно проверяйте application_token, делайте обработку идемпотентной и дочитывайте состояние объекта.

Мы в B2Bsite строим событийные интеграции с Битрикс24, которые не теряют изменения при простоях и не нагружают портал опросом. Если вам нужна синхронизация в реальном времени между Битрикс24, сайтом и учётной системой — спроектируем её на событиях.