Главное за минуту
- Входящий вебхук позволяет сайту вызвать метод REST API и создать или обновить сущность CRM.
- Исходящий вебхук отправляет внешнему сервису событие: создание лида, изменение сделки или контакта.
- URL вебхука равен ключу доступа: его нельзя хранить в JavaScript, письмах и открытых документах.
- Приёмка интеграции — это тестовая заявка, проверка полей, дублей, ответственного и журнала ошибок.
01
Вебхук: не модуль, а маршрут между системами
Вебхук в Битрикс24 — механизм обмена данными через HTTP. В одном сценарии сайт обращается к CRM по специальному URL и получает ответ. В другом CRM сама отправляет сообщение на URL внешней системы, когда произошло заданное событие.
Для маркетолога это способ сохранить источник лида, UTM-метки и состав заявки; для руководителя — убрать ручной перенос и сделать путь обращения проверяемым.
Вебхук не заменяет проектирование: до разработки нужно определить сущность CRM, обязательные поля, правила поиска дублей и действия при ошибке.
02
REST URL
Адрес входящего вебхука содержит идентификатор пользователя и секретный токен с заданными правами.
03
Два типа вебхуков и разные направления данных
Выбор зависит от инициатора обмена. Если данные нужно забрать или записать в Битрикс24 по запросу сайта, используют входящий вариант. Если внешний сервис должен узнать об изменении в CRM без опроса API, настраивают исходящий.
Входящий
- Сайт создаёт лид или сделку.
- Сервис запрашивает статус заказа.
- Скрипт обновляет контакт по телефону.
Исходящий
- CRM сообщает о новом лиде.
- Смена стадии запускает уведомление.
- Изменение сделки передаётся в учётную систему.
04
Какие задачи решает вебхук Битрикс24
На практике вебхук полезен не только для формы обратной связи. Он связывает CRM с сайтом, телефонией, складом, сервисами рассылок и внутренними кабинетами. Важно передавать не весь объект «как есть», а согласованный набор полей.
| Сценарий | Действие | Что проверить |
|---|---|---|
| Заявка с сайта | Создать лид или сделку | Телефон, UTM, источник |
| Оплата | Обновить стадию | Номер заказа, сумма |
| Новый лид | Отправить в сервис | Код ответа, повтор доставки |
| Обновление контакта | Синхронизировать поля | Поиск дублей, дата изменения |
05
Какие поля передавать в CRM
Минимальный набор определяют по процессу продаж, а не по доступности полей API. Для заявки обычно нужны имя, телефон, email, комментарий, страница отправки, источник и рекламные метки.
Телефон и email передаются в многопольном формате CRM. UTM лучше записывать в отдельные поля, а не склеивать в комментарий: так их можно использовать в отчётах и автоматизации.
Готовое сообщение
Формулировка задачи разработчику
Цель: передавать отправку формы «Получить расчёт» в Битрикс24 через входящий вебхук.
Сущность: создавать лид; при совпадении телефона не создавать дубль, а добавлять комментарий к найденной сущности.
Поля: NAME, PHONE, EMAIL, COMMENTS, SOURCE_ID, UTM_SOURCE, UTM_MEDIUM, UTM_CAMPAIGN, URL страницы и форма-источник.
Логи: сохранять дату, ID формы, HTTP-код, ответ API и текст ошибки без токена вебхука.
Приёмка: три тестовые отправки с разными UTM создают или обновляют нужную сущность; ответственный назначается по правилу CRM.
06
Как проверить интеграцию до запуска рекламы
Проверка должна проходить по полному маршруту, а не ограничиваться сообщением «заявка отправлена». Тестируйте с реальными параметрами кампании и фиксируйте идентификатор созданной CRM-сущности.
- 1
Подготовьте тест. Откройте страницу с UTM-метками и заполните форму уникальным номером телефона.
- 2
Проверьте браузер. Убедитесь, что запрос к серверному обработчику завершился успешно, без токена в клиентском коде.
- 3
Найдите запись. Откройте лид или сделку в CRM и сверяйте все поля, источник и ответственного.
- 4
Смоделируйте повтор. Повторно отправьте форму с тем же телефоном и проверьте правило дублей.
- 5
Проверьте сбой. Временно обработайте ошибку API: пользователь должен увидеть понятный ответ, а команда — запись в логе.
07
Риски доступа и надёжности
Входящий URL фактически действует как пароль с набором разрешений. Его утечка даёт возможность выполнять методы от имени пользователя вебхука. Создавайте отдельного технического пользователя, выдавайте минимальные права и заменяйте URL при подозрении на компрометацию.
Для исходящих событий внешний обработчик должен быстро вернуть HTTP 200, проверять полученные данные и быть готовым к повторной доставке. Подробные ограничения и методы описаны в документации Битрикс24.
Права
Только методы и сущности, нужные сценарию.
Секрет
URL хранится в переменных окружения сервера.
Логи
Записываются код ответа и ID сущности, но не токен.
Повторы
Обработчик не создаёт дубликат при повторном запросе.
08
Когда нужен не вебхук, а приложение
Вебхук подходит для ограниченного сценария и технической интеграции под контролем владельца портала. Если требуется авторизация разных клиентов, интерфейс внутри Битрикс24, работа от имени нескольких пользователей или распространение решения, нужен REST API через приложение.
При сложном обмене заранее согласуйте очередь запросов, сопоставление статусов, лимиты API и процедуру восстановления после недоступности одной из систем.
Практический ориентир
Начните со схемы полей и событий. Код пишут после того, как бизнес подтвердил, что именно должно произойти с данными.
Создан отдельный технический пользователь; права вебхука минимальны; токен не находится в исходном коде сайта; UTM передаются отдельными полями; правило дублей согласовано; ошибки и ID CRM записываются в лог; проверены создание и повторная отправка.
FAQ
Частые вопросы
Можно ли передавать данные из формы напрямую в URL вебхука?
Не стоит: URL с токеном окажется в коде страницы и может быть раскрыт. Используйте серверный обработчик сайта.
Вебхук работает только с лидами?
Нет. Через разрешённые методы можно работать со сделками, контактами, компаниями, задачами и другими сущностями.
Почему CRM вернула ошибку доступа?
Обычно у вебхука нет нужного разрешения, URL устарел или у пользователя изменились права.
Как отличить ошибку сайта от ошибки Битрикс24?
Смотрите журнал обработчика: URL запроса, HTTP-код, тело ответа API и ID созданной сущности.
