Клиент заполнил форму на сайте, увидел «Спасибо, мы свяжемся с вами», а менеджер так ничего и не получил. Письмо с заявкой ушло в спам, ящик читает один человек, и он в отпуске. Такие потери почти всегда обнаруживают случайно, когда клиент звонит с претензией. Интеграция сайта с Битрикс24 через вебхук решает эту проблему напрямую: заявка сразу становится лидом или сделкой в CRM, получает ответственного и попадает в воронку, где её видно руководителю. Настраивается это за день, а вот ошибки в настройке всплывают месяцами, поэтому про типичные поломки здесь написано не меньше, чем про саму схему.
Что такое вебхук в Битрикс24: входящий и исходящий
Вебхук в Битрикс24 это адрес, по которому внешняя система обращается к REST API портала без полноценного приложения и без OAuth-авторизации. Для связки «сайт и CRM» такой вариант самый короткий: не нужно публиковать приложение в Маркете, хватает прав администратора портала и небольшого серверного кода на стороне сайта.
Вебхуков два вида, и работают они в противоположных направлениях.
Входящий вебхук принимает запросы от сайта. Сайт отправляет данные на адрес вида https://ваш-портал.bitrix24.kz/rest/{ID пользователя}/{секретный код}/{метод}.json, и Битрикс24 выполняет указанный метод: создаёт лид, ищет контакт, добавляет комментарий. Именно входящий вебхук отвечает за передачу заявок с сайта в CRM.
Исходящий вебхук работает наоборот. Когда в CRM происходит событие (создана сделка, изменилась стадия), Битрикс24 отправляет POST-запрос на адрес обработчика, который вы указали. Так сайт или внешний сервис узнаёт об изменениях в CRM.
Для обычной формы «оставьте заявку» хватает входящего. Исходящий нужен, когда CRM должна что-то сообщить обратно: например, изменить статус заказа в личном кабинете покупателя.
Как заявка проходит путь от формы до сделки
Со стороны посетителя всё выглядит одинаково, но за кнопкой «Отправить» стоит цепочка из нескольких шагов, и каждый из них может отказать.
- Посетитель заполняет форму, браузер отправляет данные на сервер сайта.
- Серверный обработчик (PHP-скрипт, хук WordPress, модуль 1С-Битрикс) проверяет поля и отсекает спам.
- Обработчик формирует запрос к входящему вебхуку: название лида, имя, телефон, почта, источник, UTM-метки.
- Битрикс24 создаёт запись в CRM и возвращает её ID.
- Обработчик сохраняет ответ в журнал и только после этого показывает посетителю сообщение об успешной отправке.
- В CRM срабатывают роботы воронки: назначение ответственного, уведомление, задача перезвонить.
Пятый шаг пропускают чаще всего. Сайт показывает «спасибо» сразу, не дожидаясь ответа CRM, и если запрос не прошёл, об этом не узнаёт никто. Правильный обработчик пишет в журнал каждую попытку и при ошибке сохраняет заявку локально, чтобы отправить её повторно.
Где создаётся вебхук и какие права ему давать
Входящий вебхук создают в разделе «Приложения» → «Разработчикам» → «Готовые сценарии» → «Другое» → «Входящий вебхук». Создать его может администратор портала или сотрудник, которому выдано такое право. При создании отмечают, к каким разделам API вебхук получит доступ. Для передачи заявок достаточно раздела CRM, остальное лучше не включать.
Важная деталь из документации: вебхук выполняет запросы от имени сотрудника, который его создал, и в пределах прав этого сотрудника. Отсюда два практических следствия.
Во-первых, если создать вебхук под учётной записью директора, все лиды с сайта будут появляться в ленте как созданные директором. Если потом директору урежут права в CRM, вместе с ними урежется и интеграция. Разумнее завести отдельную служебную учётную запись, дать ей права только на создание лидов и контактов и создать вебхук под ней.
Во-вторых, секретный код в адресе вебхука фактически заменяет логин и пароль. Кто знает этот адрес, тот может работать с CRM с правами создателя вебхука. Поэтому код должен храниться только на сервере сайта, в конфигурации или переменных окружения. Встречаются сайты, где адрес вебхука прописан прямо в JavaScript формы и виден любому посетителю через «Просмотр кода страницы». При такой схеме любой желающий может читать базу клиентов или заливать в неё мусор, а форма при этом исправно работает, так что никто ничего не замечает.
Если код всё-таки утёк, создайте новый вебхук, пропишите его адрес в настройках сайта и удалите старый. Пока старый вебхук существует, его адрес продолжает работать.
Что передавать в CRM, кроме имени и телефона
Минимальная интеграция передаёт имя и телефон, и менеджеру этого хватает, чтобы перезвонить. Руководителю отдела продаж и маркетологу нужно больше: откуда пришёл клиент, с какой страницы, по какой рекламной кампании. Без этих данных через месяц невозможно ответить на вопрос, какой канал приносит сделки, а какой только расходует бюджет.
Что стоит передавать в лид:
- Название лида по понятному шаблону, например «Заявка с сайта: расчёт стоимости». По нему менеджер сразу видит, с какой формы пришёл клиент.
- Телефон и e-mail. В Битрикс24 это мультиполя: у лида может быть несколько телефонов, и каждый передаётся как отдельный элемент со значением и типом (рабочий, мобильный).
- Источник (поле
SOURCE_ID). Для заявок с сайта обычно выбирают «Веб-сайт», а если форм несколько, заводят собственные источники в справочнике CRM. - UTM-метки. У лида есть стандартные поля
UTM_SOURCE,UTM_MEDIUM,UTM_CAMPAIGN,UTM_CONTENT,UTM_TERM. Сайт должен запомнить метки при первом заходе посетителя (в cookie или сессии), иначе к моменту отправки формы они потеряются: человек мог перейти с рекламы, погулять по каталогу и отправить заявку с третьей страницы. - Адрес страницы, с которой отправлена форма, и комментарий посетителя.
- Ответственный (
ASSIGNED_BY_ID), если распределение по менеджерам не делают роботы внутри CRM. - Пользовательские поля под вашу специфику: город, интересующая услуга, выбранный тариф.
Для создания лида долго использовался метод crm.lead.add, и большинство готовых примеров в интернете написаны под него. В актуальной документации он отмечен как устаревший, а вместо него рекомендуется универсальный crm.item.add, где тип объекта задаётся параметром entityTypeId (1 для лида, 2 для сделки). Существующие интеграции на старом методе при этом продолжают работать, но новую разумно сразу писать на новом.
Лиды или сделки: сначала проверьте режим CRM
В Битрикс24 есть два режима CRM. Классический работает с лидами: заявка сначала попадает в лиды, менеджер её квалифицирует и конвертирует в сделку. Простой режим работает без лидов, всё сразу идёт в сделки.
Режим влияет на то, как поведёт себя интеграция. Согласно документации REST API, в простом режиме система автоматически конвертирует созданный через API лид в сделку, а сам лид получает статус «сконвертирован». Условие конвертации: у лида должно быть заполнено имя. Узнать текущий режим можно методом crm.settings.mode.get, он возвращает 1 для классического режима и 2 для простого.
Отсюда типичная ситуация. Компания переключает CRM в простой режим, интеграцию никто не трогает, и часть заявок перестаёт появляться в сделках. Разбор показывает, что у этих заявок было пустое поле имени: форма на лендинге просила только телефон. Лиды создавались, но без конвертации так и лежали в лидах, куда после перехода на простой режим никто не заглядывал. Поэтому при смене режима CRM интеграцию с сайтом нужно проверять отдельно, а поле имени лучше подставлять хотя бы значением вроде «Без имени», если посетитель его не заполнил.
Дубли контактов: как не плодить одного клиента десять раз
Постоянный клиент оставляет заявку третий раз за полгода. Простая интеграция создаёт новый лид с тем же телефоном, и в CRM появляется ещё одна карточка. Через год в базе десятки дублей, менеджеры спорят, чей клиент, а история общения размазана по разным записям.
Для проверки дублей в API есть метод crm.duplicate.findbycomm. Он принимает тип средства связи (телефон или e-mail) и список значений, до 20 за один запрос, и возвращает ID лидов, контактов и компаний, у которых найдено совпадение. Логика обработчика тогда выглядит так: перед созданием лида проверить телефон, и если контакт уже есть, привязать новую заявку к нему или создать сделку на существующего клиента.
Здесь есть тонкость с форматом номеров. Посетители вводят телефон как угодно: с восьмёркой, с +7, со скобками и пробелами. Если сайт не приводит номер к единому виду до отправки, проверка дублей будет промахиваться. Нормализацию номера лучше сделать на стороне сайта, это несколько строк кода.
Отдельно стоит решить, что делать с найденным дублем. Одним компаниям нужен новый лид на каждое обращение, потому что каждая заявка это отдельная продажа. Другим нужна одна карточка клиента и новые сделки внутри неё. Это бизнес-решение, и принимать его стоит до написания кода, иначе переделывать придётся уже с накопленной базой.
Лимиты API и почему заявки иногда пропадают
У REST API Битрикс24 есть ограничения на частоту запросов. По документации, на большинстве тарифов допустимая постоянная скорость составляет 2 запроса в секунду, на тарифе Enterprise 5 в секунду. Работает это по принципу «дырявого ведра»: каждый запрос увеличивает счётчик, счётчик постепенно уменьшается, и короткие всплески допускаются. Когда счётчик превышает порог (50 на обычных тарифах, 250 на Enterprise), следующие запросы получают ошибку QUERY_LIMIT_EXCEEDED с HTTP-кодом 503. Помимо частоты, учитывается и суммарное время выполнения каждого метода: при превышении API возвращает ошибку OPERATION_TIME_LIMIT.
Для сайта с десятком заявок в день эти лимиты кажутся недостижимыми. Проблема возникает, когда через тот же портал работают другие интеграции: синхронизация с учётной системой, выгрузка каталога, сервис аналитики звонков. Все они расходуют общий лимит, и запрос с сайта может попасть в момент, когда портал временно не принимает обращения.
Кроме лимитов, заявку теряют ещё по нескольким причинам:
- у сайта истёк SSL-сертификат или хостинг обновил PHP, и запросы к порталу перестали уходить;
- вебхук пересоздали, а адрес на сайте не поменяли;
- сотруднику, под которым создан вебхук, изменили права в CRM;
- в CRM добавили обязательное поле, и лид без него не создаётся;
- форму на сайте переделали, а поля в обработчике остались старые.
Защита от всех этих сценариев одна и та же: обработчик должен проверять ответ Битрикс24, писать ошибки в журнал, сохранять неотправленные заявки и повторять отправку. Плюс хотя бы резервное письмо на почту при ошибке, чтобы заявка не пропала совсем, пока интеграцию чинят.
Пример: интеграция для компании с тремя формами
Возьмём условную компанию, которая продаёт промышленное оборудование. На сайте три формы: «Запросить прайс», «Заказать звонок» и «Рассчитать проект». Реклама идёт в Google Ads и Яндекс Директе, CRM работает в классическом режиме с лидами.
Схема, которую имеет смысл собрать в таком случае:
- Под служебного пользователя «Сайт» создаётся входящий вебхук с доступом только к CRM.
- В справочнике CRM заводятся три источника по названиям форм, чтобы в отчётах сразу было видно, какая форма приносит сделки.
- Сайт сохраняет UTM-метки при первом визите и передаёт их в стандартные поля лида.
- Перед созданием лида обработчик нормализует телефон и ищет дубли. Если контакт найден, лид привязывается к нему.
- Для формы «Рассчитать проект» передаются дополнительные пользовательские поля: отрасль и примерный объём.
- Распределение по менеджерам делают роботы в воронке лидов, а не код на сайте. Так руководитель продаж может менять правила сам, не обращаясь к разработчику.
- Каждая попытка отправки пишется в журнал. При ошибке заявка сохраняется, отправка повторяется, а на почту руководителя уходит копия.
На шестом пункте экономить не стоит. Бизнес-логику (кому назначить, какую задачу поставить, какое уведомление отправить) лучше держать в Битрикс24, а сайт пусть отвечает только за доставку данных. Тогда изменения в работе отдела продаж не требуют правки кода сайта.
Если настраивать такую схему своими силами некому, её можно заказать вместе с воронками и роботами: внедрение и настройка Битрикс24 обычно включает и интеграцию форм сайта, и проверку, что UTM-метки доходят до отчётов.
Исходящий вебхук: когда CRM должна сообщить сайту
Обратная связь из CRM нужна реже, но есть задачи, где без неё не обойтись. Интернет-магазин показывает покупателю статус заказа, который меняют менеджеры в сделке. Сервис бронирования закрывает слот, когда сделка переходит в стадию «Оплачено». Партнёрский кабинет показывает агенту, сколько его клиентов дошло до покупки.
Исходящий вебхук настраивается в том же разделе для разработчиков. Выбирается событие, например добавление или изменение сделки, и указывается адрес обработчика на сайте. Когда событие происходит, Битрикс24 отправляет POST-запрос с данными в формате application/x-www-form-urlencoded.
Здесь есть три момента, которые нужно учесть при разработке.
Первый: в запросе обычно приходит только идентификатор объекта, а не все его поля. Чтобы узнать новую стадию сделки, обработчику нужно сделать встречный запрос в API через входящий вебхук.
Второй: обработчик должен проверять подлинность запроса. В каждом запросе передаётся токен приложения (auth[application_token]), и его нужно сравнивать с токеном из настроек исходящего вебхука. Без этой проверки кто угодно, узнав адрес обработчика, сможет отправлять сайту поддельные события.
Третий: адрес обработчика должен быть доступен из интернета и работать по HTTPS с действующим сертификатом. Обработчик на локальном сервере или за корпоративным файрволом события не получит.
Вебхук, CRM-форма или готовый модуль
Связать сайт с Битрикс24 можно не только вебхуком, и для простых сайтов он бывает избыточен.
CRM-формы Битрикс24 встраиваются на сайт готовым кодом и создают лиды без программирования. Это разумный вариант, когда форма простая, а дизайн формы Битрикс24 устраивает. Ограничения начинаются, если форму нужно полностью встроить в дизайн сайта или добавить сложную логику проверки.
Готовые модули и плагины для WordPress и других CMS связывают формы с CRM через настройки в админке. Они экономят время на старте, но у каждого свои ограничения по полям, UTM и работе с дублями, и при обновлении CMS они иногда перестают работать. Подробнее о подводных камнях для WordPress мы писали в статье об интеграции WordPress с CRM.
Собственный обработчик на вебхуке требует разработки, зато даёт полный контроль: какие поля передавать, как искать дубли, что делать при ошибке. Для сайтов, где заявки напрямую приносят выручку, этот контроль обычно окупается.
Приложение с OAuth нужно, если одна интеграция должна работать с несколькими порталами Битрикс24 или встраиваться в интерфейс CRM. Для связки одного сайта с одним порталом это избыточно.
Что проверить после запуска
Интеграцию, которую один раз проверили тестовой заявкой, нельзя считать работающей. Проверьте сразу после запуска и потом раз в месяц:
- каждая форма сайта создаёт запись в CRM, включая формы в попапах и на лендингах;
- заявка с рекламной ссылкой приносит в лид все UTM-метки;
- повторная заявка с тем же телефоном не создаёт дубль контакта;
- ответственный назначается правильно, уведомление приходит;
- при недоступности портала заявка не теряется, а сохраняется и уходит повторно;
- адрес вебхука не виден в исходном коде страницы;
- число заявок в журнале сайта совпадает с числом лидов в CRM за тот же период.
Последний пункт самый показательный. Если за месяц сайт принял 140 заявок, а в CRM 128 лидов, интеграция где-то теряет данные, даже если каждая тестовая отправка проходит успешно.
Частые вопросы
Нужен ли программист, чтобы подключить сайт к Битрикс24 через вебхук?
Создать сам вебхук может администратор портала за несколько минут. Обработчик на стороне сайта, который принимает форму, проверяет данные и отправляет их в CRM, пишется кодом. Если нужна простая форма без доработок, можно обойтись CRM-формой Битрикс24 без программирования.
Безопасно ли использовать вебхук?
Да, если секретный код хранится только на сервере сайта, а вебхук создан под служебным пользователем с минимальными правами. Опасно размещать адрес вебхука в JavaScript на странице: тогда он доступен любому посетителю.
Почему заявка с сайта не появилась в сделках?
Частые причины: CRM работает в простом режиме, а у лида не заполнено имя, поэтому он не сконвертировался в сделку; сработал лимит запросов к API; изменились права пользователя, под которым создан вебхук; в CRM появилось обязательное поле. Начинать стоит с журнала ошибок обработчика на сайте.
Можно ли передавать в Битрикс24 UTM-метки из формы?
Можно. У лида есть стандартные поля для пяти UTM-меток. Главное, чтобы сайт сохранял метки при первом заходе посетителя, а не пытался прочитать их из адреса страницы в момент отправки формы.
Чем входящий вебхук отличается от исходящего?
Входящий принимает запросы от внешней системы и выполняет методы API: так сайт создаёт лиды. Исходящий сам отправляет запросы на указанный адрес, когда в CRM происходит событие: так сайт узнаёт, например, об изменении стадии сделки.