Вебхуки Битрикс24: входящие и исходящие, архитектура интеграции

Что такое вебхуки

Вебхук — это HTTP-уведомление, которое одна система отправляет другой при каком-либо событии. Битрикс24 поддерживает 2 типа:

• Входящий вебхук — внешняя система вызывает методы Битрикс через специальный URL
• Исходящий вебхук — Битрикс отправляет POST-запрос на ваш URL, когда происходит событие

Вместе они закрывают 80% типовых сценариев интеграции.

Входящий вебхук

Создание:

1. Зайти в Битрикс24 как администратор
2. Разработчикам → Другое → Входящий вебхук
3. Назначить права (CRM, задачи, пользователи и т.д.)
4. Сохранить — получить URL

Пример URL: https://portal.bitrix24.ru/rest/1/abc123def456/

Вызов любого метода:

POST https://portal.bitrix24.ru/rest/1/abc123def456/crm.deal.add.json
Content-Type: application/json

{"fields":{"TITLE":"Сделка из веб-формы","STAGE_ID":"NEW"}}

Готово — сделка создана.

Исходящий вебхук

Битрикс отправляет данные при событии. Создание:

1. Разработчикам → Другое → Исходящий вебхук
2. Указать ваш URL (где будет принимать)
3. Выбрать событие (например, ONCRMDEALADD)
4. Указать ключ (для проверки подлинности)

Когда событие происходит, Битрикс делает POST на ваш URL:

POST https://your-server.com/webhook
event=ONCRMDEALADD
data[FIELDS][ID]=12345
auth[application_token]=...

Вы обрабатываете и отвечаете 200 OK.

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

• ONCRMLEADADD/UPDATE/DELETE — лиды
• ONCRMDEALADD/UPDATE/DELETE — сделки
• ONCRMCONTACTADD/UPDATE/DELETE — контакты
• ONCRMACTIVITYADD/UPDATE — активности (звонки, письма)
• ONTASKADD/UPDATE/DELETE — задачи
• ONIMBOTMESSAGEADD — сообщения боту

Полный список — в документации Битрикс.

Архитектура простой интеграции

Сценарий: при создании сделки в Битрикс — отправлять уведомление в Telegram.

1. Создать исходящий вебхук на ONCRMDEALADD с URL вашего сервера
2. На вашем сервере (PHP/Python/Node) — endpoint, принимающий POST
3. В обработчике: получить ID сделки, получить детали через входящий вебхук, отправить в Telegram через Bot API
4. Ответить 200 OK

Полный цикл — 30–50 строк кода.

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

Вебхуки используют секретные токены в URL. Если URL попадёт к злоумышленникам — они могут управлять вашим Битрикс.

Меры:

• Хранить URL только в защищённых местах (env, секреты)
• Не коммитить в Git
• Регулярно ротировать токены
• Для исходящих — проверять подпись (application_token)
• HTTPS обязателен

Обработка нагрузки

Если событий много (например, активный CRM с десятками сделок в час) — обрабатывайте асинхронно:

1. Получили вебхук — поставили в очередь (Redis, RabbitMQ)
2. Сразу ответили 200 OK
3. Воркер обрабатывает из очереди

Иначе медленный обработчик блокирует Битрикс.

Идемпотентность

Битрикс может повторно отправить вебхук (например, при ошибке вашего сервера). Обработчик должен быть идемпотентным:

• Проверять, не обработан ли уже это событие
• Использовать уникальные ID для предотвращения дублей

Логирование

Логировать:

• Каждый входящий вебхук (что пришло, когда)
• Каждый исходящий вызов API (что отправили, что получили)
• Ошибки с подробностями

Без логов отладка интеграций — кошмар.

Тестирование

Способы:

• ngrok — проксирует ваш локальный сервер для тестирования вебхуков
• webhook.site — для проверки, что Битрикс отправляет правильно
• Postman — для проверки входящих вебхуков

Частые ошибки

• URL вебхука в публичном репозитории — взлом
• Синхронная обработка медленных операций — таймауты
• Не обрабатывают повторы — дубли
• Нет логов — нечем отлаживать
• Отвечают не 200 — Битрикс ретраит

Сколько стоит интеграция через вебхуки

Простая (1 направление, 1–2 события): 15 000–40 000 ₽.

Полная двусторонняя (Битрикс ↔ ваша система): 50 000–200 000 ₽.

Рассчитать →   Записаться на разбор →

FAQ

Что лучше: вебхуки или приложение?

Для одного портала + простых сценариев — вебхуки. Для приложения, продаваемого многим — OAuth-приложение.

Можно ли несколько обработчиков на одно событие?

Да, можно создать несколько исходящих вебхуков на одно событие.