Главное за минуту
- REST API — набор методов для чтения и изменения CRM; вебхук — способ вызвать метод или получить событие.
- Для одной серверной формы обычно достаточно входящего вебхука с правами только на нужные сущности.
- Для внешнего сервиса, нескольких порталов и авторизации пользователей выбирают приложение с OAuth.
- Исходящий вебхук нужен, когда CRM сама должна сообщить сайту или сервису об изменении.
01
Начните с маршрута заявки, а не с выбора термина
Маркетологу нужен измеримый результат: форма сайта создала лид или сделку, менеджер увидел телефон и UTM, а источник можно проверить в отчёте. Разработчику для этого требуется способ отправить запрос в CRM и, иногда, получить ответное событие.
REST API Битрикс24 — это методы вроде создания лида, поиска контакта или обновления сделки. Входящий вебхук даёт серверу сайта URL с авторизацией для вызова этих методов. Исходящий вебхук, наоборот, отправляет уведомление из CRM на ваш URL.
Поэтому вопрос «REST API или вебхук» чаще всего некорректен: вебхук может быть каналом работы с REST API либо механизмом доставки события.
02
REST URL
Адрес определяет портал, пользователя и права, с которыми сайт вызывает методы CRM.
03
Какой вариант подходит вашему сценарию
Выбирайте не самый быстрый способ настройки, а тот, который переживёт смену сотрудника, рост числа форм и подключение внешних сервисов. Доступы должны соответствовать одной задаче, а не открывать CRM целиком.
Для сайта важно разделить отправку данных в CRM и реакцию сайта на изменения в CRM. Это два разных направления обмена, и они могут использоваться вместе.
Сайт отправляет в CRM
- Входящий вебхук — одна форма или внутренний сервис.
- OAuth-приложение — SaaS, несколько клиентов или порталов.
- REST-методы создают и обновляют лиды, контакты, сделки.
CRM сообщает наружу
- Исходящий вебхук — изменение стадии, лида или сделки.
- Получатель проверяет подпись, формат и повтор события.
- Подходит для уведомлений, статусов заказа и синхронизации.
04
Сравнение способов доступа к данным CRM
Входящий вебхук удобен для серверной части сайта: ключ не попадает в браузер, а вызов ограничен правами пользователя. Но он привязан к конкретному порталу и учётной записи.
OAuth требует больше разработки, зато подходит для тиражируемого решения: каждый клиент выдаёт доступ самостоятельно, а токены можно обновлять по правилам приложения.
| Способ | Когда выбирать | Главный риск |
|---|---|---|
| Входящий вебхук | Один сайт и один портал | Секрет в фронтенде или чате |
| OAuth-приложение | Внешний продукт, много порталов | Нет обработки истечения токена |
| Исходящий вебхук | CRM инициирует уведомление | Не учтены повторы доставки |
| Робот CRM | Простой сценарий внутри портала | Логика скрыта от сайта |
05
Какие данные передавать из формы
Не передавайте в CRM весь POST-запрос формы. Зафиксируйте карту полей: что создаёт сущность, что нужно отделу продаж, что нужно маркетингу для атрибуции и что является техническим идентификатором.
Телефон и email нормализуют, согласие на обработку фиксируют отдельно, а UTM сохраняют без подмены. Для повторной отправки нужен ключ идемпотентности: например, ID заявки сайта.
Готовое сообщение
Готовая постановка задачи разработчику
Цель. Передавать заявки формы «Консультация» с сайта в Битрикс24 не позднее одной минуты после отправки.
Метод. Сервер сайта вызывает REST API через входящий вебхук; URL и секрет хранятся только в настройках сервера.
Поля. Имя, телефон, email, комментарий, страница, дата, form_id, client_id и UTM: source, medium, campaign, content, term.
Логика. При совпадении телефона создать запись по согласованному правилу либо добавить комментарий к существующей; решение зафиксировать до разработки.
Ошибки. Сохранять код ответа CRM, ID заявки и текст ошибки; повторять временно неуспешный запрос, но не создавать дубли.
Приёмка. Проверить три тестовые заявки с разными UTM, повторную отправку и недоступность CRM.
06
Маршрут проверки после запуска
Принимать интеграцию должен не только разработчик. Менеджер по маркетингу проходит путь посетителя, затем сверяет карточку CRM и журнал отправок. Проверка занимает 15–20 минут и выявляет большую часть ошибок до старта рекламы.
- 1
Отправьте тестовую форму. Используйте отдельные телефон и email, чтобы быстро найти запись.
- 2
Добавьте UTM. Откройте страницу с utm_source, utm_medium и utm_campaign, затем проверьте их в CRM.
- 3
Сверьте сущность. Убедитесь, что создан именно лид или сделка в нужной воронке и с ответственным.
- 4
Проверьте повтор. Отправьте форму ещё раз и убедитесь, что сработало согласованное правило дублей.
- 5
Посмотрите журнал. В логе должны быть ID заявки, время, метод, HTTP-код и ID CRM-сущности.
07
Ошибки, из-за которых интеграция становится уязвимой
Самая опасная практика — вызвать REST URL прямо из JavaScript. Любой посетитель увидит секрет в исходном коде или сетевых запросах и сможет использовать права вебхука.
Ключ должен жить в переменных окружения сервера. Создайте отдельного технического пользователя, выдайте минимальные права и заранее определите, кто меняет ключ при увольнении сотрудника.
Сервер
Запрос к CRM идёт только из PHP-бэкенда сайта.
Права
Доступ ограничен CRM и нужными действиями.
Логи
Секреты и персональные данные не пишутся целиком.
Повторы
Обработчик не создаёт дубль при повторной доставке.
08
Когда без подрядчика лучше не начинать
Нужна отдельная проработка, если сайт передаёт заказы, оплаты и статусы доставки, объединяет несколько CRM или должен работать при недоступности одного из сервисов. Здесь важны очередь, повторная доставка, мониторинг и правила разрешения конфликтов.
Документацию по методам и ограничениям стоит сверять с REST API Битрикс24. Для сложного сценария полезно сначала описать карту данных и ответственность систем.
Секрет не передаётся в браузер; поля и воронка согласованы; UTM проверены; дубли обработаны; есть журнал ошибок; назначен владелец доступов.
FAQ
Частые вопросы
Можно ли использовать вебхук вместо REST API?
Входящий вебхук вызывает методы REST API с заранее выданными правами. Это не замена методам, а способ авторизации запроса.
Что выбрать для одной формы на сайте?
Обычно серверный вызов через входящий вебхук. Если форма простая, сначала согласуйте поля, сущность CRM и защиту от дублей.
Нужен ли исходящий вебхук для создания лида?
Нет. Он нужен для обратного направления: когда Битрикс24 должен уведомить сайт или внешний сервис об изменении.
Почему заявка есть в журнале сайта, но нет в CRM?
Проверьте HTTP-код и ответ метода, права вебхука, обязательные поля, лимиты и правило обработки дублей.
Можно ли передать UTM в стандартные поля?
Можно, если поля и отчётность согласованы заранее. Часто удобнее создать отдельные поля или сохранять значения в комментарии и источнике.
