При интеграции CRM с внешним сервисом часто возникает задача: получать уведомления о новых сделках, лидах или звонках без постоянного опроса API. Вебхуки решают это, отправляя HTTP-запрос сразу после события. Как указано в документации Битрикс24: вебхуки позволяют получать уведомления о событиях в реальном времени. За 10+ лет мы настроили такие механизмы для 50+ проектов: от уведомлений в Telegram до синхронизации с 1С. Ниже — технические детали, чтобы избежать типичных ошибок и сэкономить до 40% времени на интеграцию.
Два типа вебхуков
Входящий вебхук (Inbound). Внешняя система вызывает Битрикс24. Вы получаете фиксированный URL вида https://domain.bitrix24.ru/rest/1/хэш_токена/метод.json и можете вызывать любые REST-методы без OAuth-авторизации. Используется для отправки данных в Битрикс24 из сторонних систем.
Исходящий вебхук (Outbound). Битрикс24 вызывает внешнюю систему при наступлении события. Вы подписываетесь на конкретные события (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND и др.) и указываете URL обработчика. При наступлении события Битрикс24 POST-ом отправляет данные на этот URL.
Почему исходящие вебхуки эффективнее поллинга?
В отличие от поллинга, вебхуки работают в реальном времени: событие → HTTP-запрос за секунды. Это быстрее поллинга в 10 раз и снижает нагрузку на сервер. Для большинства сценариев (уведомления, синхронизация) этого достаточно. Если требуется гарантированная доставка — используем очередь и повторные попытки.
Как настроить исходящий вебхук под вашу задачу?
В разделе «Разработчикам → Другое → Исходящий вебхук» выберите событие из списка. Основные события для CRM:
-
ONCRMLEADADD/ONCRMLEADUPDATE— лид создан / изменён -
ONCRMDEALADD/ONCRMDEALUPDATE/ONCRMDEALDELETE— сделка -
ONCRMCONTACTADD/ONCRMCONTACTUPDATE— контакт -
ONCRMCOMPANYADD/ONCRMCOMPANYUPDATE— компания -
ONCRMACTIVITYADD— добавлено дело (звонок, письмо, встреча) -
ONVOXIMPLANTCALLEND— завершён звонок (телефония) -
ONTASKUPDATE— обновление задачи
В поле «Адрес обработчика» укажите URL внешнего сервиса. Битрикс24 отправляет POST-запрос с application/x-www-form-urlencoded телом, содержащим данные события.
| Событие | Тип | Пример использования |
|---|---|---|
ONCRMDEALADD |
Сделка | Уведомление в Telegram о новой сделке |
ONVOXIMPLANTCALLEND |
Звонок | Запись звонка в стороннюю CRM |
ONTASKUPDATE |
Задача | Синхронизация статуса задачи с внешним таск-трекером |
Структура входящего запроса
Тело запроса от Битрикс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 считает доставку неудачной. Повторных попыток по умолчанию нет (в отличие от полноценных приложений с очередями событий).
Правильный паттерн:
- Принять запрос, ответить 200
- Поставить задачу в очередь (Redis, RabbitMQ, БД)
- Обработать асинхронно
Пример обработчика на PHP
<?php // Получаем данные вебхука $data = $_POST; // Сразу отвечаем 200 http_response_code(200); // Ставим задачу в очередь (например, через Redis) $redis->lpush('webhook_queue', json_encode($data)); Если обработка синхронная и занимает больше 3–5 секунд — Битрикс24 фиксирует таймаут.
Какие меры безопасности необходимы?
Вебхук-эндпоинт публично доступен из интернета — это нужно учитывать. Меры защиты:
- Проверка токена. В URL входящего вебхука есть токен — валидируем его на стороне обработчика
- IP-whitelist. Разрешаем запросы только с IP-адресов Битрикс24 (список публикуется в документации)
- HMAC-подпись. Для локальных приложений доступна подпись запроса — проверяем
X-Bitrix-Hmac-Sha256заголовок
Ограничения и особенности
Вебхуки работают в рамках лимитов REST API: 2 запроса в секунду для облачного Битрикс24 (на входящие вебхуки). При массовых операциях (импорт 1000 сделок) каждое создание генерирует событие — обработчик должен справляться с пиковой нагрузкой.
Для коробочного Битрикс24 лимиты выше и настраиваются в файле /bitrix/.settings.php. События обрабатываются синхронно в рамках того же PHP-процесса, что создаёт нагрузку при частых событиях.
| Аспект | Облачный Битрикс24 | Коробочный |
|---|---|---|
| Лимит REST API | 2 запроса/сек | Настраивается |
| Повторные попытки | Нет | Нет (без дополнительных решений) |
| Список событий | Стандартный | Расширяется через AddEventHandler |
| Кастомные события | Только через приложение | Через \Bitrix\Main\EventManager |
Типичные ошибки при настройке вебхуков
- Синхронная обработка — приводит к таймаутам. Решение: асинхронная очередь.
- Игнорирование IP-фильтрации — эндпоинт уязвим для поддельных запросов.
- Отсутствие логирования — сложно отлаживать сбои доставки.
Что входит в работу?
- Аудит текущей архитектуры и выбор типа вебхуков
- Настройка исходящих/входящих вебхуков с нужными событиями
- Разработка обработчика с асинхронной очередью (Redis, RabbitMQ)
- Документация по эндпоинтам и безопасности
- Тестирование под нагрузкой и гарантия доставки
- Обучение вашей команды работе с вебхуками
Средняя стоимость настройки одного вебхука с обработчиком — от $100–250. в зависимости от сложности и необходимого стека. Весь процесс занимает от 1 до 5 дней.
Если нужна надёжная интеграция без потери событий — свяжитесь с нами. Оценим проект бесплатно и предложим оптимальное решение. Закажите настройку вебхуков под вашу архитектуру – получите гарантию доставки и безопасность.