Настройка вебхуков для внешних интеграций Битрикс24

Настройка вебхуков для внешних интеграций Битрикс24

Вебхук — механизм, при котором Битрикс24 сам уведомляет внешнюю систему о событии, не заставляя её постоянно опрашивать API. Новая сделка, смена стадии, входящий звонок — Битрикс24 отправляет HTTP-запрос на указанный URL в течение нескольких секунд. Это основной инструмент для построения интеграций без разработки полноценного приложения.

Два типа вебхуков

Входящий вебхук (Inbound webhook). Внешняя система вызывает Битрикс24. Вы получаете фиксированный URL вида https://domain.bitrix24.ru/rest/1/хэш_токена/метод.json и можете вызывать любые REST-методы без OAuth-авторизации. Используется для отправки данных в Битрикс24 из сторонних систем.

Исходящий вебхук (Outbound webhook). Битрикс24 вызывает внешнюю систему при наступлении события. Вы подписываетесь на конкретные события (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND и др.) и указываете URL обработчика. При наступлении события Битрикс24 POST-ом отправляет данные на этот URL.

Настройка исходящего вебхука

В разделе «Разработчикам → Другое → Исходящий вебхук» выбираем событие из списка. Основные события для CRM:

• ONCRMLEADADD / ONCRMLEAD UPDATE — лид создан / изменён
• ONCRMDEALADD / ONCRMDEALUPDATE / ONCRMDEALDELETE — сделка
• ONCRMCONTACTADD / ONCRMCONTACTUPDATE — контакт
• ONCRMCOMPANYADD / ONCRMCOMPANYUPDATE — компания
• ONCRMACTIVITYADD — добавлено дело (звонок, письмо, встреча)
• ONVOXIMPLANTCALLEND — завершён звонок (телефония)
• ONTASKUPDATE — обновление задачи

В поле «Адрес обработчика» указываем URL внешнего сервиса. Битрикс24 отправляет POST-запрос с application/x-www-form-urlencoded телом, содержащим данные события.

Структура входящего запроса

Тело запроса от Битрикс24 содержит:

event=ONCRMDEALUPDATE
&auth[access_token]=...
&auth[domain]=domain.bitrix24.ru
&data[FIELDS][ID]=12345
&data[FIELDS][STAGE_ID]=WON

Поле data[FIELDS] содержит изменённые поля сущности. Для получения полного состояния объекта нужно сделать отдельный запрос через REST API (crm.deal.get с id=12345), используя токен из auth.

Обработчик на стороне внешней системы

Принципиальное требование: обработчик должен ответить HTTP 200 в течение нескольких секунд. Если ответ не пришёл или код отличен от 2xx — Битрикс24 считает доставку неудачной. Повторных попыток по умолчанию нет (в отличие от полноценных приложений с очередями событий).

Правильный паттерн:

1. Принять запрос, ответить 200
2. Поставить задачу в очередь (Redis, RabbitMQ, БД)
3. Обработать асинхронно

Если обработка синхронная и занимает больше 3–5 секунд — Битрикс24 фиксирует таймаут.

Безопасность

Вебхук-эндпоинт публично доступен из интернета — это нужно учитывать. Меры защиты:

• Проверка токена. В URL входящего вебхука есть токен — валидируем его на стороне обработчика
• IP-whitelist. Разрешаем запросы только с IP-адресов Битрикс24 (список публикуется в документации)
• HMAC-подпись. Для локальных приложений доступна подпись запроса — проверяем X-Bitrix-Hmac-Sha256 заголовок

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

Вебхуки работают в рамках лимитов REST API: 2 запроса в секунду для облачного Битрикс24 (на входящие вебхуки). При массовых операциях (импорт 1000 сделок) каждое создание генерирует событие — обработчик должен справляться с пиковой нагрузкой.

Для коробочного Битрикс24 лимиты выше и настраиваются в файле /bitrix/.settings.php. События обрабатываются синхронно в рамках того же PHP-процесса, что создаёт нагрузку при частых событиях.

Вебхуки — быстрый способ связать Битрикс24 с внешней системой без сложной инфраструктуры. Для простых сценариев (уведомление в Telegram при новой сделке, синхронизация с таблицей Google Sheets) этого достаточно. Для сложных интеграций с гарантией доставки и обработкой ошибок нужна полноценная архитектура с очередью и приложением.