Главное за минуту
- Вебхук не является формой: он принимает или отправляет данные между системами по заданному сценарию.
- Для сайта обычно нужен входящий вебхук: сервер формы вызывает метод API Битрикс24 после проверки данных.
- В заявку стоит передавать источник, страницу, UTM-метки, согласие и технический идентификатор отправки.
- Секретный URL нельзя размещать в JavaScript браузера, письмах, публичных документах и системах аналитики.
- Работу принимают тестовыми заявками: проверяют карточку CRM, ответственного, дубли и журнал ошибок.
01
Вебхук — маршрут между формой и CRM, а не отдельная кнопка
Когда посетитель оставляет номер телефона на сайте, менеджеру важно получить не просто текст сообщения. Нужны контакты, выбранная услуга или товар, страница отправки, рекламный источник и понятный статус обработки. Если эти сведения переносят вручную из почты или таблицы, часть заявок теряется, а маркетинг не может связать обращение с рекламной кампанией.
Вебхук решает задачу передачи: это URL с правами доступа, по которому одна система вызывает метод другой. В сценарии сайта запрос обычно идёт с серверной части формы в API Битрикс24. CRM получает набор полей, создаёт или обновляет нужную сущность и возвращает технический ответ: выполнена операция или возникла ошибка.
Сам вебхук не определяет бизнес-процесс. Он не решает, создавать лид, контакт, сделку или обращение в открытой линии. Это должно быть описано до разработки. Например: заявка с формы «Запросить расчёт» создаёт лид, ответственный определяется по направлению, а UTM-метки сохраняются в отдельных полях. Для интернет-магазина маршрут может быть другим: запрос привязывается к существующему клиенту и заказу.
Маркетологу полезно воспринимать интеграцию как цепочку с контрольными точками: посетитель заполнил форму → сайт проверил обязательные поля и согласие → сервер передал данные → Битрикс24 записал их в карточку → сотрудник получил уведомление. Вебхук находится в середине этой цепочки. Если заявка не появилась в CRM, нужно искать не «сломанный вебхук вообще», а конкретный участок, где исчезли данные.
02
REST URL
Защищённый адрес определяет, от имени какого пользователя и с какими правами сайт обращается к CRM.
03
Какой вебхук нужен форме сайта
В Битрикс24 различают входящие и исходящие вебхуки. Названия описывают направление относительно CRM, поэтому их легко перепутать при постановке задачи. Для отправки заполненной формы с сайта в Битрикс24 разработчик чаще всего использует входящий вебхук: сайт отправляет запрос внутрь портала и вызывает разрешённый REST-метод.
Исходящий вебхук работает иначе. Сначала в Битрикс24 происходит событие — например, изменён статус элемента CRM, — а затем портал уведомляет внешний URL. Такая схема пригодится, если сайт, складская система или личный кабинет должны узнать об изменении в CRM. Она не заменяет приём первичной заявки с лендинга.
У входящего вебхука есть пользователь-владелец и набор прав. Если выдать доступ администратора «на всякий случай», секретный URL сможет выполнить больше действий, чем требуется форме. Если владелец уволится, его права изменятся или пользователь будет деактивирован, интеграция может перестать работать. Поэтому владельца, права и место хранения секрета нужно зафиксировать в документации проекта.
Официальная справка Битрикс24 по REST и вебхукам поможет сверить термины и доступные методы: документация Битрикс24. Для постановки задачи достаточно указать направление, сущность CRM и права; способ вызова и обработку ответа определяет разработчик.
Входящий вебхук
- Сайт вызывает API Битрикс24.
- Подходит для приёма формы.
- Нужны права на запись в CRM.
Исходящий вебхук
- Битрикс24 вызывает внешний URL.
- Подходит для уведомлений о событиях.
- Нужен доступный обработчик на стороне получателя.
04
Какие данные передавать вместе с заявкой
Ошибка многих интеграций — ограничиться именем и телефоном. Менеджер перезвонит, но руководитель маркетинга не поймёт, с какой страницы пришёл клиент, какая кампания сработала и что именно интересовало посетителя. Впоследствии такие заявки невозможно корректно сегментировать или сопоставить с расходами.
Сначала составьте карту полей формы и карточки CRM. Для каждого значения нужно определить источник, формат, обязательность и действие при пустом значении. Телефон лучше передавать в стандартное поле CRM, а не в комментарий: тогда поиск дублей и телефония будут работать предсказуемо. Согласие на обработку персональных данных стоит сохранять с текстом или версией документа и временем отправки.
Рекламные параметры не должны зависеть от видимости полей в форме. Сайт считывает UTM из URL, сохраняет их на время визита по согласованной логике и передаёт при отправке. Отдельно полезно передать URL страницы, referer, название формы и идентификатор заявки сайта. Последний позволит сопоставить запись в логе сайта с объектом CRM при расследовании ошибки.
Не передавайте через форму пароли, платёжные реквизиты, паспортные данные и другие сведения, которые не требуются для первого обращения. Чем меньше чувствительных данных проходит через интеграцию, тем проще обеспечить законное хранение и ограничить последствия инцидента.
| Данные | Куда записать | Проверка |
|---|---|---|
| Имя, телефон, email | Стандартные поля CRM | Формат телефона и email |
| Услуга или товар | Поле или комментарий | Соответствует выбору в форме |
| utm_source, utm_campaign | Отдельные пользовательские поля | Не пропадают после переходов |
| URL и название формы | Технические поля | Совпадают с местом отправки |
| Согласие и время | Поле согласия или комментарий | Есть у каждой записи |
05
Безопасная схема: секрет остаётся на сервере
URL входящего вебхука содержит секрет. Тот, кто получил этот адрес, потенциально может выполнить методы CRM в пределах выданных прав. Поэтому нельзя вставлять URL прямо в JavaScript формы. Любой посетитель откроет код страницы или вкладку Network в браузере и увидит адрес. Ограничение CORS не делает опубликованный секрет безопасным.
Правильный маршрут строится через серверный обработчик сайта. Браузер отправляет форму на ваш домен. Обработчик проверяет обязательные поля, антиспам, согласие и допустимую длину значений. Затем сервер добавляет технические данные, обращается к API Битрикс24 и записывает результат в журнал. В браузер возвращается нейтральный ответ: заявка принята или повторите попытку позднее.
Если сайт работает на 1С-Битрикс, обработчик можно реализовать в компоненте, модуле или отдельном контроллере в зависимости от архитектуры проекта. Важно не просто «отправить curl-запрос», а предусмотреть тайм-аут, проверку HTTP-ответа, обработку ошибок API и защиту от повторной отправки. Конкретные REST-методы и их параметры описаны на портале разработчика 1С-Битрикс.
Доступ к настройке вебхука должны иметь только назначенные сотрудники. Храните URL в переменных окружения или закрытой конфигурации сервера, не в репозитории и не в публичном файле. При смене подрядчика передавайте доступ контролируемо либо создавайте новый вебхук после завершения работ.
Не маскируйте утечку заменой символов
Если полный URL уже попал в переписку, скриншот, систему аналитики или публичный код, его нужно удалить из источника и перевыпустить вебхук. Смена нескольких видимых символов в документе не отзывает скомпрометированный ключ.
Готовое сообщение
Тема: интеграция формы сайта с Битрикс24 через входящий вебхук.
Нужно настроить передачу формы «Получить консультацию» с сайта в CRM. После успешной валидации сервер сайта должен создать лид. URL вебхука и любые секреты хранятся только в серверной конфигурации; в браузерный JavaScript не передаются.
Передавать: имя, телефон, email, текст обращения, выбранную услугу, URL страницы, название формы, utm_source, utm_medium, utm_campaign, utm_content, utm_term, время отправки и признак согласия. Телефон и email записывать в стандартные поля лида; метки — в отдельные пользовательские поля.
Нужны проверка обязательных полей, антиспам, защита от двойного клика и логирование ошибок без записи секретного URL. При неуспешном ответе CRM форма не должна показывать посетителю технический текст API.
Критерии приёмки: пять тестовых заявок с разными UTM появляются в CRM с верными полями; повторная отправка не создаёт дубль по согласованному правилу; ответственный назначается по правилам CRM; в журнале видны дата, идентификатор заявки и результат вызова.
06
Как проверить интеграцию до запуска рекламы
Приёмка не должна ограничиваться сообщением разработчика «данные приходят». Проверять нужно полный бизнес-сценарий: что видит посетитель, какую карточку получает менеджер и может ли маркетолог найти источник обращения. Назначьте одного ответственного за тест со стороны бизнеса: он подготовит сценарии, будет отправлять формы и сверит результат в CRM.
Начните с тестового окружения или отдельной тестовой формы, если оно предусмотрено. Если проверяете на рабочем портале, помечайте записи понятным префиксом и удаляйте их после теста. Не используйте реальные номера клиентов и не запускайте массовые запросы: вы создадите шум в воронке и можете вызвать ограничения API.
Отдельно проверьте форму на мобильном устройстве, отправку с UTM-параметрами, отсутствие меток, ошибочный номер, повторный клик и временную недоступность CRM. Последний сценарий важен: посетитель должен получить корректное сообщение, а команда — сигнал о том, что заявки требуют повторной отправки или ручной обработки.
Результат проверки фиксируйте в таблице либо задаче. Скриншоты можно приложить из реального тестового портала; для публичных материалов лучше использовать обезличенные примеры или кейсы из портфолио ICONICA, а не создавать псевдоскриншоты интерфейса.
- 1
Подготовьте сценарии. Укажите форму, страницу, значения полей, UTM и ожидаемый объект CRM.
- 2
Отправьте тест. Проверьте сообщение пользователю и отсутствие технических ошибок в браузере.
- 3
Откройте CRM. Сверьте тип сущности, поля, ответственного, стадию и дату создания.
- 4
Найдите источник. Убедитесь, что UTM, URL и название формы доступны для отчёта.
- 5
Проверьте сбой. Отключите тестовый доступ или используйте контролируемую ошибку и оцените лог.
07
Где заявки пропадают и как быстрее найти причину
Если форма показала успех, а записи в CRM нет, не стоит сразу создавать новую интеграцию. Сначала сопоставьте время отправки, идентификатор заявки и логи сайта. У формы, серверного обработчика и Битрикс24 разные зоны ответственности: проблема может быть в валидации, блокировке антиспамом, сетевом запросе, правах вебхука или правилах автоматизации CRM.
Часто заявка всё же создана, но менеджер её не видит. Причины — неверное направление, статус, ответственный, права просмотра или правило распределения. Вторая частая ситуация: запись есть, но в ней нет UTM. Тогда нужно проверить, когда сайт сохраняет метки, не теряются ли они при переходе между доменами и совпадают ли коды полей CRM с теми, что использует обработчик.
В журнале должны быть безопасные диагностические данные: дата, ID отправки, имя формы, HTTP-код, метод API, ID созданного объекта и текст ошибки без секретов и персональных данных в открытом виде. Это сокращает время поиска и помогает отличить единичный сбой от системной проблемы.
Настройте уведомление ответственному, если число ошибок превышает согласованный порог или CRM недоступна несколько минут. Постоянно смотреть журнал не нужно, но отсутствие контроля превращает техническую ошибку в потерянные обращения.
08
Когда достаточно вебхука, а когда нужен другой способ
Входящий вебхук подходит для понятного одностороннего действия: принять форму, создать или обновить сущность CRM, передать комментарий и служебные параметры. Он удобен, когда сайт и портал уже определены, а объём операций умеренный. Но вебхук не отменяет проектирование интеграции, если между системами есть сложные правила.
Например, для проверки остатков, расчёта персональной цены, двусторонней синхронизации каталога или обмена с несколькими сервисами может потребоваться отдельный API-сервис, очередь задач и повторная обработка запросов. Если нужно реагировать на изменение статуса в CRM на внешней стороне, добавляется исходящий вебхук или подписка на события. Выбор зависит не от модного названия технологии, а от маршрута данных и последствий ошибки.
До начала работ ответьте на четыре вопроса: кто инициирует обмен, какие данные считаются источником истины, что происходит при недоступности одной из систем и как команда узнаёт о сбое. Эти ответы помогают оценить объём работ и не превратить простую форму в непрозрачную связку.
Признак достаточной схемы
Если форма передаёт ограниченный набор данных в один портал, результат можно проверить тестовой карточкой, а ошибки логируются и не теряются, входящего вебхука с серверным обработчиком обычно достаточно.
Определён объект CRM и ответственный; секрет не попадает в браузер; UTM и URL страницы передаются; настроена защита от повторной отправки; есть журнал ошибок; выполнены тесты с метками и без них; владелец вебхука и доступы зафиксированы
09
Что решить перед подключением вебхука
Вебхук в Битрикс24 нужен форме не сам по себе, а для контролируемого маршрута заявки в CRM. Начните не с генерации URL, а с решения, какую сущность нужно создать, кто отвечает за неё, какие поля обязательны и где будут храниться данные об источнике. После этого вебхук становится техническим каналом с понятными правами, а не неизвестной ссылкой в настройках.
Для обычной лид-формы безопасная базовая схема выглядит так: браузер отправляет данные на сервер сайта, сервер валидирует их и вызывает API через входящий вебхук, CRM возвращает ID созданной записи, а обработчик пишет безопасный результат в журнал. Не размещайте секретный адрес на странице и не выдавайте ему права шире необходимых.
Перед запуском рекламы сделайте контрольные отправки с разными UTM, без меток и с повторным кликом. Проверьте карточку CRM глазами менеджера и маркетолога: первый должен быстро обработать обращение, второй — определить источник. Если требуется несколько направлений, сложное распределение, двусторонний обмен или нет доступа к серверной части сайта, подключайте подрядчика на этапе проектирования. Исправлять потерянные заявки после старта кампании дороже, чем согласовать маршрут и критерии приёмки заранее.
FAQ
Частые вопросы
Вебхук и API Битрикс24 — это одно и то же?
Нет. API — набор правил и методов для работы с системой. Вебхук — один из способов авторизованно вызвать эти методы по URL.
Можно ли отправлять форму прямо из JavaScript в Битрикс24?
Технически это возможно, но секрет вебхука станет доступен посетителям. Для рабочей формы запрос нужно выполнять с сервера сайта.
Создавать лид или сделку после формы?
Это определяется вашей воронкой. Для первичного неразобранного обращения часто используют лид, но в порталах без лидов заявка может сразу стать сделкой.
Почему CRM создаёт несколько одинаковых заявок?
Чаще всего посетитель нажимает кнопку несколько раз либо обработчик повторяет запрос после тайм-аута. Нужны блокировка кнопки и правило поиска дублей.
Нужно ли менять вебхук при смене сотрудника?
Если вебхук создан от имени уходящего пользователя или его права изменятся, лучше заранее создать новый под сервисной учётной записью и заменить конфигурацию.
