Вебхуки: как получать события из CRM
Вебхук — это «мост» между Битрикс24 и внешней системой. Входящий вебхук позволяет внешней системе вызывать методы Битрикс24: создать сделку, обновить контакт, получить список задач. Исходящий — наоборот: Битрикс24 отправляет событие (например, «сделка создана») на ваш сервер, и вы реагируете.
В 2027 году вебхуки остаются самым быстрым способом интеграции для одного портала. Не нужно создавать приложение, проходить OAuth, публиковать решение в Маркетплейсе. Достаточно создать вебхук, выбрать `scope` и отправить запрос.
Но у простоты есть обратная сторона: вебхук — это пароль. Если URL попадёт в публичный репозиторий или клиентский код, доступ к данным получит кто угодно. В этой статье — как работают входящие и исходящие вебхуки, как настроить, где ошибаются и как не потерять данные. Если нужна разработка интеграции через API — поможем.
Содержание статьи
Входящий вебхук
Входящий вебхук вызывает методы REST API по секретному URL. Запросы выполняются от имени сотрудника, который создал вебхук, и в рамках выбранного `scope`.
Когда использовать
- Быстрые интеграции — форма на сайте создаёт лид в CRM;
- Тесты — проверить метод в браузере или через `curl`;
- Скрипты — массовое обновление данных;
- Обмен с внешней системой — если интеграция работает только с одним порталом.
Как создать
- Откройте *Приложения > Разработчикам*;
- Перейдите на вкладку *Готовые сценарии > Другое > Входящий вебхук*;
- Выберите метод, заполните параметры, нажмите *Выполнить* для теста;
- Укажите права доступа (`scope`) и нажмите *Создать*.
Как устроен URL
https://example.bitrix24.ru/rest/1/xxxxxxxx/department.get.json?ID=42
Где `/1` — ID сотрудника, `xxxxxxxx` — секретный код, `department.get` — метод.
💡 Важно
Часть методов через вебхук недоступна: встраивание виджетов (`placement.bind`), часть методов телефонии, некоторые сценарии чат-ботов. Они требуют контекста приложения.
Исходящий вебхук
Исходящий вебхук отправляет событие Битрикс24 на ваш URL. Вы регистрируете обработчик, выбираете события, и когда они происходят — Битрикс24 отправляет POST-запрос.
Когда использовать
- Реакция на изменение данных — сделка перешла на стадию, отправьте уведомление;
- Запуск синхронизации — новый контакт, обновите внешнюю базу;
- Уведомление внешней системы — задача создана, отправьте в мессенджер.
Как создать
- Откройте *Разработчикам > Другое > Исходящий вебхук*;
- Укажите URL обработчика;
- Выберите события (например, `OnCrmDealAdd`);
- Сохраните. Токен приложения сгенерируется автоматически .
Что приходит в обработчик
Событие сообщает только о факте изменения. В запросе приходят:
- event — код события;
- data[FIELDS][ID] — ID изменённого объекта;
- auth[application_token] — токен для проверки подлинности.
Чтобы получить данные объекта, нужен дополнительный вызов метода, например `crm.deal.get` .
Очередь событий
Битрикс24 не вызывает обработчик напрямую. Событие попадает в очередь на специальном сервере, и только оттуда уходит POST-запрос на ваш URL. Из-за этого возможна небольшая задержка.
Что важно
- Скорость ответа — если обработчик отвечает медленно, сервер снижает частоту вызовов;
- Пиковая нагрузка — массовое обновление сделок может создать очередь из тысяч событий;
- Нет повторной отправки — если обработчик упал или вернул ошибку, событие не переотправляется.
Поэтому обработчик должен быть готов к пиковой нагрузке и отвечать быстро. Рекомендуется использовать «входящую очередь» на своей стороне: принимать запрос, ставить в очередь и обрабатывать асинхронно.
💡 Важно
Если ваш обработчик не ответил или вернул ошибку 5xx, Битрикс24 не будет повторять отправку. Событие потеряно. Поэтому для критичных сценариев нужна своя очередь и логирование.
Безопасность
Вебхук — это ключ доступа. Если URL попадёт не туда, данные утекут.
Правила
- Не публиковать — URL вебхука не должен быть в клиентском коде, публичных репозиториях, логах;
- HTTPS — только защищённое соединение;
- Проверка токена — в исходящем вебхуке сравнивайте `auth[application_token]` с токеном в настройках;
- Минимум scope — не выдавайте все права «на всякий случай».
Если вебхук скомпрометирован
Битрикс24 может заблокировать вебхук, если секретный код обнаружен в публичном доступе. В этом случае нужно сгенерировать новый код в настройках.
Ошибка `INVALID_CREDENTIALS` означает, что вебхук заблокирован или код неверен.
Ошибки
1. Публикация URL вебхука
Секретный код в клиентском коде или публичном репозитории — доступ к данным получат посторонние.
2. Медленный обработчик
Битрикс24 снижает частоту вызовов, если обработчик отвечает медленно. События накапливаются в очереди.
3. Нет проверки токена
Обработчик принимает запросы от кого угодно. Нужно сравнивать `auth[application_token]`.
4. Ожидание данных в событии
Событие сообщает только ID. Данные нужно запрашивать отдельным методом .
5. Обработчик на localhost
URL обработчика должен быть доступен из внешней сети. localhost и локальные адреса не работают.
6. Нет своей очереди
При пиковой нагрузке обработчик падает, события теряются. Нужна входящая очередь.
Наши рекомендации
Что вы получаете, заказывая настройку вебхуков у нас
- Входящий вебхук — для вызова методов
- Исходящий вебхук — для событий
- Проверка безопасности — scope, токен, HTTPS
- Обработчик — с очередью и логированием
- Документация — для команды
📌 Итоговый вывод
Вебхук — это быстрый способ интеграции. Но с ним нужно обращаться как с паролем.
Что нужно знать:
- Входящий: вызов методов по секретному URL от имени создателя;
- Исходящий: отправка событий на ваш URL ;
- Очередь: события идут через сервер очередей, возможна задержка;
- Безопасность: не публиковать URL, проверять токен, минимум scope;
- Ошибки: публикация URL, медленный обработчик, нет проверки, localhost, нет очереди.
Также рекомендуем: API, методы REST API, авторизация, все статьи об API.