Заявка с сайта падает в Bitrix24, но менеджер должен сначала узнать об этом — а потом ещё свериться с CRM, чтобы понять, что делать дальше. Пока он это делает, конкурент уже позвонил клиенту. Входящий webhook (webhook — это URL-адрес, на который Bitrix24 сам отправляет данные при определённом событии, без необходимости постоянно опрашивать систему) решает именно эту задачу: он толкает данные туда, где их ждут, в момент события, а не через час при следующей проверке почты.
В этой статье разберём, как настроить и правильно обработать входящий webhook в Bitrix24: от создания обработчика до частых ошибок, которые встречаются почти в каждом первом проекте интеграции. Подходит для разработчиков, которые уже работают с REST API Bitrix24 или начинают это делать.
Ключевая фраза, с которой сюда обычно приходят — «bitrix24 webhook настройка и обработка входящих событий» — и именно это мы разберём по шагам.
Что понадобится перед началом
- Доступ к порталу Bitrix24 с правами администратора (без этого нельзя создавать обработчики событий)
- Публично доступный URL, на который Bitrix24 будет отправлять данные (HTTPS обязателен — на HTTP-адрес события не доставляются)
- Базовое понимание REST API Bitrix24: что такое метод, что такое access_token
- PHP 7.4+ или Node.js 16+ — в зависимости от того, на чём пишете обработчик
- Тестовый портал Bitrix24 (бесплатный, регистрируется за 5 минут) — крайне желательно не тестировать на продакшене
Основная часть: создаём и настраиваем webhook
Шаг 1. Создаём входящий вебхук в портале
Входящий вебхук — это URL с токеном, который Bitrix24 генерирует сам, и через который внешние системы могут вызывать методы REST API. Это не то же самое, что событие — это просто способ подключения к API без OAuth.
Идём в раздел «Разработчикам» → «Другое» → «Входящий вебхук». Выбираем нужные права доступа (например, crm — для работы с лидами и сделками) и нажимаем «Сохранить». Bitrix24 выдаёт URL вида https://yourportal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/.
Частая ошибка: выдают вебхуку права на всё подряд «на всякий случай». Это создаёт риск безопасности — если токен утечёт, у атакующего будет доступ ко всему порталу. Выдавайте только то, что реально нужно для задачи.
Шаг 2. Различаем входящий и исходящий webhook
Это путают чаще всего. Входящий webhook — вы вызываете методы Bitrix24 (например, добавляете лид). Исходящий webhook — Bitrix24 вызывает ваш URL при определённом событии (например, при создании сделки). Для обработки «входящих событий», о которых речь в этой статье, нужен именно исходящий webhook со стороны Bitrix24 — несмотря на путающее название, для вашей системы он именно «входящий» поток данных.
Настраивается в том же разделе «Разработчикам» → «Другое» → «Исходящий вебхук». Указываете событие (например, ONCRMLEADADD) и URL вашего обработчика.
Шаг 3. Пишем обработчик на стороне сервера
Bitrix24 отправляет данные POST-запросом в формате application/x-www-form-urlencoded, а не JSON — это вторая частая засада для тех, кто привык работать с REST API в JSON.
<?php
// Получаем данные из POST-запроса Bitrix24
$data = $_POST;
// Проверяем, что событие действительно от лида
if (isset($data['event']) && $data['event'] === 'ONCRMLEADADD') {
$leadId = $data['data']['FIELDS']['ID'];
// Дальше можно дёргать REST API, чтобы получить полные данные по лиду
// т.к. вебхук присылает только ID, а не весь набор полей
}
http_response_code(200); // обязательно отвечаем 200, иначе Bitrix24 будет ретраить запрос
Частая ошибка: забывают вернуть HTTP 200. Если сервер не ответит кодом 200, Bitrix24 решит, что доставка не удалась, и будет повторять запрос — в итоге один лид может прийти 5-10 раз.
Шаг 4. Проверяем подпись запроса (опционально, но важно)
Bitrix24 не подписывает исходящие webhook криптографически по умолчанию, в отличие от некоторых других систем (например, Stripe). Это значит, что теоретически кто угодно может отправить POST-запрос на ваш URL, имитируя событие Bitrix24.
Минимальная защита — проверять, что в запросе передаётся application_token, который выдаётся при настройке вебхука, и сверять его на своей стороне перед обработкой.
// Сверяем токен приложения, чтобы отсечь поддельные запросы
if ($data['auth']['application_token'] !== getenv('BITRIX_APP_TOKEN')) {
http_response_code(403);
exit;
}
Шаг 5. Обрабатываем дозагрузку данных через REST API
Как уже сказали в шаге 3, webhook присылает не все поля, а только ID изменённой сущности. Чтобы получить полные данные, нужно сделать дополнительный запрос к REST API методом crm.lead.get.
$leadId = $data['data']['FIELDS']['ID'];
$webhookUrl = 'https://yourportal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/';
$response = file_get_contents($webhookUrl . 'crm.lead.get.json?id=' . $leadId);
$leadData = json_decode($response, true);
Частая ошибка: пытаются вытащить нужные поля прямо из тела webhook-запроса и удивляются, что там пусто. В событии всегда минимум данных — за остальным нужно идти в API отдельно.
Шаг 6. Настраиваем идемпотентность обработчика
Поскольку Bitrix24 может присылать повторные запросы (ретраи при сетевых сбоях, задержках ответа и так далее), обработчик должен быть готов получить одно и то же событие дважды и не создать дубликат записи.
Самый простой способ — сохранять ID обработанных событий (или ID сущности + timestamp) в отдельную таблицу и проверять перед обработкой.
Частые ошибки и как их избежать
Ошибка: обработчик отвечает дольше 5-10 секунд. Возникает, когда в обработчике сразу делают тяжёлую логику — например, синхронные запросы к нескольким внешним системам. Bitrix24 ждёт ответ ограниченное время, и при таймауте считает доставку неуспешной и повторяет запрос. Решение: в обработчике быстро сохраняем данные в очередь (например, в таблицу или Redis) и отвечаем 200, а тяжёлую обработку делаем асинхронно.
Ошибка: тестируют webhook на продакшн-портале с реальными клиентами. Возникает из экономии времени на настройку тестового портала. Решение: регистрируем бесплатный тестовый Bitrix24-портал — это 5 минут, а отлавливать баги на реальных лидах потом стоит куда дороже.
Ошибка: не учитывают, что событие приходит до того, как транзакция в Bitrix24 полностью завершена. В редких случаях запрос на получение полных данных по только что созданной сущности (шаг 5) может вернуть неполные данные, если делать его мгновенно. Решение: при странном поведении добавить небольшую задержку (1-2 секунды) перед запросом полных данных.
Ошибка: вебхук настроен, но события не приходят. Чаще всего причина — обработчик висит на HTTP, а не HTTPS, или сертификат самоподписанный. Bitrix24 не отправляет данные на недоверенные сертификаты. Решение: проверить сертификат через любой online SSL-чекер.
Из нашей практики
Перед тем как вешать автоматизацию на событие, всегда проверяем на тестовом портале, какие поля у сделки или лида помечены как обязательные — и что происходит, если webhook присылает данные без одного из них. На практике процессы у клиентов почти всегда завязаны на роботов и бизнес-процессы, и если обязательное поле приходит пустым, автоматизация не падает с понятной ошибкой, а просто тихо не срабатывает или зависает на середине цепочки — потом два дня разбираешься, почему письмо клиенту не ушло.
Отдельная история — когда источник данных (сайт, форма, сторонний сервис) ещё не приводит данные в нужном формате, а под них в Bitrix24 не созданы свои поля. Заводить поле в CRM под каждый чих — не вариант, это долго и часто незачем, если данные приходят раз в неделю на этапе обсуждения интеграции. В таких случаях временно пишем всё, что прилетело, в комментарий к сделке или лиду, но не как сплошной текст, а строкой с разделителем — например, источник: сайт | utm_campaign: spring_sale | страница: /promo | устройство: mobile. Когда становится понятно, какие поля реально нужны постоянно, под них создают normal-поля в CRM, и эту же строку из комментария парсят скриптом и дозаполняют исторические записи — переделывать интеграцию с нуля не приходится.
Из этого же вытекает правило, которое спасло не один проект: на этапе обработки webhook лучше сохранять данных с избытком, а не ровно столько, сколько нужно сегодня. Поля, которые сейчас кажутся бесполезными (timestamp события, raw-данные запроса, ID связанных сущностей), через месяц-два почти всегда становятся нужны — либо для отладки, когда что-то пошло не так, либо потому что бизнес захотел новый отчёт. Дешевле хранить лишнее в JSON-поле или комментарии, чем потом восстанавливать утраченные данные задним числом, а это в большинстве случаев невозможно.
Итог
После этой настройки заявки, сделки и изменения в Bitrix24 будут долетать до вашей системы автоматически и почти мгновенно — без опроса API по таймеру и без задержек в час-два. Если на каком-то шаге застряли — опишите ситуацию в комментарии или напишите нам напрямую.
CTA
Нужна помощь с интеграцией Bitrix24 под вашу задачу — запишитесь на консультацию