Вебхуки Битрикс24: что это и как с ними работать
Вебхуки — самый простой способ связать Битрикс24 с сайтом или другим сервисом без разработки полноценного приложения. Рассказываем, как работают входящие и исходящие вебхуки, как их создать, какие права давать, как их не «засветить» и почему интеграция иногда внезапно перестаёт работать.
Входящий вебхук
Это адрес, по которому внешняя система может вызывать методы REST API Битрикс24 от имени пользователя, создавшего вебхук. Например, сайт создаёт лид, когда посетитель заполнил форму, или учётная система обновляет статус сделки.
Адрес выглядит так: https://портал.bitrix24.ru/rest/ID_пользователя/секретный_код/. К нему добавляется название метода, например crm.lead.add.json, и параметры запроса.
Как создать
- Откройте раздел для разработчиков в портале и выберите создание входящего вебхука.
- Выберите права — только те разделы, которые нужны интеграции.
- Сохраните и скопируйте адрес — он показывается в настройках вебхука.
- Передайте адрес разработчику интеграции по защищённому каналу.
Пример использования
Сайт отправляет заявку:
POST https://портал.bitrix24.ru/rest/7/секретный_код/crm.lead.add.json
fields[TITLE]=Заявка с сайта
fields[NAME]=Иван
fields[PHONE][0][VALUE]=+79130000000В ответ приходит номер созданного лида или описание ошибки. Ошибки нужно записывать в журнал на стороне сайта, а заявку — сохранять, чтобы отправить повторно, если Битрикс24 был недоступен.
Исходящий вебхук
Обратное направление: Битрикс24 сам отправляет запрос на ваш адрес, когда происходит событие — создана сделка, изменился контакт, добавлена задача. Ваш сервер получает уведомление и выполняет нужное действие.
Важно: в уведомлении приходит идентификатор изменённой записи, а не все данные. Чтобы получить подробности, нужно отдельно запросить запись через входящий вебхук или API.
Ещё один вариант исходящего вызова — робот «Исходящий вебхук» на стадии сделки: когда сделка попадает на стадию, Битрикс24 отправляет запрос на ваш адрес с нужными данными. Это удобно для простых сценариев без программирования на стороне портала.
Права вебхука
При создании вебхука выбираются разделы, к которым он даёт доступ: CRM, задачи, пользователи, диск и другие. Давайте только нужные права: для формы сайта достаточно CRM.
| Задача | Нужные права |
|---|---|
| Форма сайта создаёт лиды | CRM |
| Учётная система обновляет сделки | CRM |
| Сервис создаёт задачи | Задачи |
| Выгрузка в отчёты | CRM, при необходимости пользователи |
Безопасность
- Вебхук — это пароль. Любой, кто знает адрес, получит те же права. Не публикуйте его в коде сайта, в открытых репозиториях, в переписке и на скриншотах.
- Храните на сервере — в конфигурации, а не в репозитории.
- Минимальные права — отдельный вебхук под каждую задачу.
- Если адрес утёк — удалите вебхук и создайте новый. Это занимает минуту и надёжнее, чем надеяться, что никто не заметил.
- Создавайте от технического пользователя, а не от сотрудника, который может уволиться.
- Проверяйте входящие уведомления — в исходящем вебхуке есть ключ, по которому можно убедиться, что запрос пришёл от вашего портала.
Вебхук или приложение
- Вебхук — простая интеграция для своего портала.
- Приложение — если интеграция ставится в несколько порталов, нужен интерфейс внутри Битрикс24 или авторизация пользователей.
Подробнее — в руководстве по REST API.
Где вебхуки используют чаще всего
- формы сайта и калькуляторы — подробнее в статье об интеграции сайта;
- связь с учётными системами, если нет готового коннектора;
- уведомления в мессенджеры и другие сервисы;
- триггеры, которые переводят сделку по событию из внешней системы — подробнее в статье о триггерах;
- выгрузка данных в отчёты и таблицы.
Частые ошибки
- В адрес добавляют лишнее, например
profile.json, а потом к нему дописывают метод — запрос не работает. Адрес вебхука должен заканчиваться на секретный код и слеш. - Вебхук создан от уволенного сотрудника — после отключения пользователя интеграция ломается.
- У вебхука полный доступ ко всему порталу.
- Нет журнала ошибок — заявки с сайта не доходят, и никто об этом не знает.
- Не учтены лимиты — массовая загрузка без пауз упирается в ограничение частоты запросов.
- Адрес отправили в общий чат — вебхук фактически скомпрометирован.
Частые вопросы
Можно ли ограничить вебхук по IP?
Штатно вебхук ограничивается правами. Для дополнительной защиты проксируйте запросы через свой сервер и не раскрывайте адрес вебхука клиентам.
Нужно ли продлевать вебхук?
Нет, входящий вебхук работает, пока его не удалили и пока активен пользователь, от которого он создан.
Работают ли вебхуки на бесплатном тарифе?
Возможности REST API и вебхуков зависят от тарифа — уточняйте для вашего портала.
Нужна интеграция под ключ — разработка для Битрикс24.