Чем входящий вебхук отличается от исходящего в Битрикс24

01

Разница — в направлении команды и владельце сценария

Слово «вебхук» часто используют для любой интеграции между сайтом и Битрикс24. Из-за этого в задаче появляется формулировка «настроить вебхук», но неясно, кто должен начать обмен и какой результат нужен. Для разработки это две разные схемы, права доступа и способы контроля ошибок.

Входящий вебхук работает так: внешний сервис отправляет HTTP-запрос в Битрикс24 и вызывает REST-метод. Например, сервер сайта после отправки формы вызывает метод создания лида или сделки, передаёт имя, телефон, страницу, UTM-метки и идентификатор заявки. Битрикс24 в этой схеме принимает команду и возвращает ответ: успех, ID сущности либо описание ошибки.

Исходящий вебхук Битрикс24 работает в обратную сторону. В CRM происходит событие — создан лид, изменена сделка, добавлен контакт — и портал отправляет уведомление на адрес внешнего обработчика. Дальше уже сайт, складская система или промежуточный сервис решает, что сделать с сообщением: обновить статус заказа, выдать доступ, записать данные в BI или поставить задачу сотруднику.

Практическое правило для маркетолога: если нужно «записать данные в CRM», сначала рассматривают входящий вебхук. Если нужно «узнать, что менеджер изменил в CRM», рассматривают исходящий. В одной интеграции они могут использоваться вместе, но не заменяют друг друга. До согласования разработки полезно нарисовать две стрелки: откуда пришло действие и где должен появиться измеримый результат.

03

Что фактически передаёт каждая схема

Входящий запрос похож на поручение: «создай сделку», «найди контакт по телефону», «добавь комментарий». В нём всегда есть метод и параметры. Разработчик должен отдельно согласовать обязательные поля CRM, формат телефона, источник, ответственного, стадию, связь с существующим контактом и пользовательские поля. Если передать только имя и телефон, лид может создаться, но маркетинг потеряет кампанию, страницу входа и корректную атрибуцию.

Исходящий запрос похож на уведомление: «в сделке изменились данные». Он не означает, что внешняя система автоматически получила полную и актуальную карточку во всех нужных полях. Обработчик должен знать, какое событие подписано, какие идентификаторы приходят в полезной нагрузке и требуется ли после уведомления запросить детали сущности через API. Это принципиально для синхронизации статусов и остатков.

В проектной документации не пишут «передать всё». Нужна таблица соответствия: поле источника, поле Битрикс24, формат, правило пустого значения и владелец данных. Для UTM это особенно важно: нужно решить, хранить первый, последний или оба визита, а также не перезаписывать метки при повторном обращении клиента.

04

Аудит сценария: где вебхук выбран неправильно

Неправильный тип вебхука редко проявляется сразу. Форма может успешно создавать лиды, но сайт не узнает, что сделка оплачена. Или CRM отправляет уведомление о новом лиде, а внешнему сервису на самом деле нужно создать этот лид по данным формы. В результате появляются ручные операции, неполные карточки и спорные отчёты по рекламе.

Проверять нужно не название настройки, а бизнес-событие. Сформулируйте его в одном предложении: «После успешной оплаты на сайте обновить стадию сделки» или «После смены стадии сделки отправить номер заказа в систему доставки». Первая часть показывает источник события, вторая — получателя действия. Так легче увидеть, нужна ли команда в CRM, уведомление из CRM или двусторонний обмен.

Если процесс двухсторонний, задайте правило приоритета. Например, статус оплаты меняет только платёжный сервис, а менеджер в Битрикс24 видит его как справочное поле. Иначе вебхук может зациклиться: CRM обновляет сайт, сайт отправляет обновление обратно, CRM снова генерирует событие.

05

Безопасность входящего вебхука: токен не должен попасть на сайт

URL входящего вебхука обычно содержит токен авторизации. Тот, кто получил полный адрес, потенциально может выполнять методы от имени пользователя в пределах выданных прав. Поэтому нельзя помещать URL в JavaScript страницы, мобильное приложение без защищённого сервера, репозиторий с открытым доступом, скриншот задачи или переписку без необходимости.

Правильная схема для формы сайта выглядит так: браузер отправляет данные на сервер сайта; сервер валидирует поля, защищается от спама и только затем вызывает API Битрикс24. Токен хранится в переменной окружения или защищённой конфигурации, доступной ограниченному кругу администраторов. Если токен уже оказался в истории репозитория или в консоли браузера, его следует немедленно заменить, а не просто удалить из текущего файла.

Права входящего вебхука выдавайте по принципу минимальности. Для записи заявок не нужен доступ к пользователям, диску и настройкам портала. Лучше создать отдельного технического пользователя с понятным именем и правами под конкретную интеграцию. При увольнении сотрудника или смене подрядчика это снизит риск остановки обмена и несанкционированного доступа.

06

Как принять интеграцию без доступа к коду

Маркетологу или руководителю не нужно самостоятельно вызывать REST-методы, но нужен воспроизводимый набор тестов. Попросите подрядчика провести демонстрацию на тестовой форме и тестовой сделке, а не только показать успешный запрос в консоли. Приёмка строится вокруг данных, которые видит бизнес: карточка CRM, источник, UTM, ответственный, статус и время реакции.

Заранее подготовьте тестовые значения, которые невозможно спутать с реальными: телефон, содержащий согласованную комбинацию цифр, email на техническом домене и UTM Campaign вроде webhook_acceptance. Тогда легко найти запись в CRM, в серверном логе и в аналитической выгрузке. Фиксируйте время отправки: оно поможет оценить задержку и отладить несоответствия.

Вторая обязательная часть — негативные сценарии. Отключите обработчик или передайте неверное обязательное поле на тестовом контуре. Система не должна молча терять заявку. Пользователь сайта должен получить нейтральное сообщение, а ответственные — увидеть запись об ошибке и способ повторить отправку.

1. 1

   Зафиксируйте маршрут. Укажите источник, действие, получателя и ожидаемое поле или статус в результате.

2. 2

   Проверьте входящую заявку. Отправьте форму с тестовыми UTM и сверьте карточку CRM по каждому полю.

3. 3

   Проверьте уведомление. Измените тестовую сделку и убедитесь, что внешний обработчик получил событие.

4. 4

   Создайте повтор. Повторите запрос с тем же внешним ID и проверьте правило дедупликации.

5. 5

   Запросите журнал. Получите время, код ответа, идентификатор сущности и текст ошибки для неуспешного теста.

07

Какие вопросы задать подрядчику до запуска

Самый полезный вопрос — не «поддерживает ли система вебхуки», а «какой именно обработчик отвечает за каждую сторону обмена». В ответе должны прозвучать URL получателя, список событий, метод API, правила повторной попытки и место, где хранится журнал. Если исполнитель отвечает только «настроим через API», задача ещё не готова к оценке.

Уточните ограничения конкретного портала и тарифа до начала работ. Набор доступных событий, права доступа и настройки могут зависеть от редакции и конфигурации Битрикс24. Официальное описание REST и вебхуков полезно сверять с документацией: вебхуки и приложения Битрикс24. Для сложных связок стоит отдельно согласовать тестовый контур и порядок переключения на рабочий.

Если в цепочке есть платёжная система, доставка, 1С или личный кабинет, попросите назвать источник истины для заказа, оплаты и статуса доставки. Вебхук доставляет сообщение, но сам не разрешает конфликт данных. Это решение должно быть в бизнес-правиле, а не оставаться догадкой программиста.

08

Когда достаточно вебхука, а когда нужен полноценный API-сервис

Вебхук подходит для понятных операций с ограниченным числом полей и событий: передать заявку, создать контакт, уведомить внешний сервис о смене статуса. Он быстро запускается и не требует разработки отдельного приложения, если права и объём обмена контролируемы.

Отдельный интеграционный сервис нужен, когда обмен включает очереди, большой поток данных, несколько систем, сложную трансформацию, регулярную синхронизацию или строгие требования к мониторингу. В такой архитектуре вебхук остаётся точкой входа для события, но обработчик ставит его в очередь, ведёт журнал, повторяет временно неуспешные операции и контролирует идемпотентность.

Не оценивайте решение только по скорости первого запуска. Если заявка влияет на выручку, а статус заказа — на клиентский опыт, стоимость отсутствующего лога или неучтённого дубля обычно выше, чем короткая техническая проработка. На проектах ICONICA перед доработкой полезно пройти маршрут данных и сверить его с реальными процессами; примеры задач по сайтам и интеграциям собраны в портфолио ICONICA.

09

Какое решение принять по итогам проверки

Начните не с настройки вебхука, а с одного маршрута данных. Если внешний сервис должен изменить Битрикс24, ему нужен входящий запрос с минимально необходимыми правами. Если Битрикс24 должен сообщить о событии вовне, нужен исходящий вебхук и доступный обработчик. Для двустороннего процесса эти маршруты описывают отдельно: с разными правилами запуска, владельцами полей и тестами.

Перед запуском проверьте три вещи: полный набор бизнес-полей в CRM, недоступность токена из браузера и возможность найти каждую неуспешную передачу по журналу. Не принимайте формулировку «вебхук работает» без тестовой заявки, изменения тестовой сделки и проверки повтора. Успешный HTTP-ответ сам по себе не доказывает, что данные попали в нужную карточку и не создали дубль.

Подрядчика стоит подключать, когда в обмене участвуют несколько систем, статусы могут меняться в обе стороны, нет владельца данных или нужна безопасная серверная обработка формы. Чёткая карта событий и критерии приёмки сократят число итераций и позволят контролировать результат без погружения в код.