Входящий вебхук Битрикс24: создать и безопасно проверить
Показываем путь в интерфейсе Битрикс24, первую безопасную проверку и разбор отказов. Полный адрес вебхука содержит секрет — храните его как пароль.
Входящий вебхук нужен, когда внешний скрипт или сервис должен вызвать метод REST API в одном Битрикс24. Например, прочитать данные сделки для внутреннего отчёта. Вебхук действует от имени сотрудника, который его создал. Поэтому до копирования URL стоит решить, какой метод будет вызван и что этот сотрудник действительно вправе видеть.
Где создать входящий вебхук
Путь в актуальной справке Битрикс24: «Разработчикам → Готовые сценарии → Другое → Входящий вебхук». В настройках выбирают scope, проверяют метод в генераторе и нажимают «Создать». Если пункт не показывается, право на создание вебхуков может быть закрыто администратором. Окно с предложением сменить тариф означает, что нужно проверить доступ к REST API.
Откройте «Разработчикам»
В Битрикс24 перейдите в «Готовые сценарии → Другое → Входящий вебхук». Если пункта нет, попросите администратора проверить право на создание.
Выберите права для будущего метода
В «Настройке прав» отметьте только нужные scope. Для первой проверки методом profile отдельный scope не нужен.
Проверьте profile в генераторе
Выберите метод без параметров и нажмите «Выполнить». Успешный ответ содержит result с данными пользователя.
Сохраните и создайте вебхук
Скопируйте URL в защищённое место и нажмите «Создать». Не размещайте адрес в репозитории, браузерном коде и публичных инструкциях.
Повторите вызов из внешней системы
С серверной стороны отправьте HTTPS POST на сохранённый адрес с методом profile.json и пустым JSON-объектом. Сверьте result с пользователем вебхука.
Проверьте целевой метод на тестовой записи
Сверьте scope на странице метода, права создателя вебхука и ответ API. Для рабочих вызовов используйте HTTPS и POST.
Для метода profile параметры не нужны. В успешном ответе поле result содержит данные сотрудника, от имени которого прошёл вызов. Это проверка авторизации, а не подтверждение доступа ко всем объектам CRM. Выбор между вебхуком и приложением зависит от того, работает ли решение на одном портале или будет устанавливаться на разных.
Чтобы проверить вызов извне, возьмите полный URL вебхука из настроек и на стороне своего сервера отправьте POST по HTTPS на путь /rest/{user_id}/{webhook_code}/profile.json с пустым JSON-объектом {}. Домен берите из собственного Битрикс24, а секретный код — из сохранённого URL. Ожидаемый признак успеха — result с ID создателя вебхука. Не копируйте полный адрес в публичный онлайн-клиент запросов: он содержит ключ доступа.
Какие права нужны для рабочего метода
На выполнение влияют три условия: доступ к REST API на портале, выбранный scope вебхука и права сотрудника на нужный объект. Например, запрос к CRM требует scope crm, но один scope не откроет сделку, которую создатель вебхука не вправе читать. Описание конкретного метода покажет нужный scope и параметры.
Выдавайте вебхуку только нужные scope. Если для интеграции требуется множество действий с разными правами, разделите сценарии и подумайте, подходит ли постоянный секрет одного сотрудника. Часть методов, например встраивание виджетов, требует контекста приложения и через вебхук недоступна.
Как обращаться с секретным URL
В URL вебхука находятся ID сотрудника и секретный код. Любой, кто получил полный адрес, может вызывать разрешённые методы в пределах прав вебхука. Не вставляйте его в JavaScript публичной страницы, репозиторий, скриншот или журнал запросов. Храните адрес на стороне сервера в защищённом хранилище и отправляйте рабочие запросы по HTTPS.
Для рабочего вызова документация рекомендует POST. Простой GET-тест в адресной строке возможен, но оставляет секрет в истории браузера и может попасть в логи. Если код оказался доступен посторонним, перегенерируйте его в настройках и замените URL во всех вызывающих системах. После смены владельца вебхука проверьте права заново: запросы будут идти от другого сотрудника.
Почему вызов не работает
При ошибке методов прежней версии API посмотрите и error, и error_description. Отказ по правам и отказ из-за подписки требуют разных действий. Если profile работает, а метод CRM нет, сначала проверьте scope и доступ пользователя к конкретной записи.
| Код | Что означает | Проверка |
|---|---|---|
| INVALID_CREDENTIALS | Вебхук не найден по ID и коду: ошибка адреса, удаление, истечение срока или смена кода | Скопировать актуальный URL из настроек; при замене кода обновить интеграцию |
| insufficient_scope | Методу не выдан нужный scope | Сверить scope метода и «Настройку прав» вебхука |
| ACCESS_DENIED | Недостаточно прав на объект; при сообщении о подписке REST недоступен по тарифу | Прочитать error_description, проверить права сотрудника и доступ к REST |
| ERROR_METHOD_NOT_FOUND | Неверное имя или отсутствующий метод | Сверить название с официальным справочником |
Когда вебхука уже недостаточно
Входящий вебхук привязан к одному порталу и сотруднику. Если решение должны устанавливать разные компании, нужен сценарий приложения с OAuth 2.0. Для реакции на события Битрикс24 используют исходящий вебхук или события приложения; входящий вебхук сам не отправляет уведомлений наружу. Подходящий способ зависит от архитектуры интеграции и доступности нужных методов.
Когда внешней системе нужен сигнал об изменении сделки, смотрите настройку и проверку исходящего вебхука.
Если вы только планируете обмен с другой системой, начните с одного события и одного проверяемого действия. Для полей CRM полезны карта соответствия данных и разбор кодов API.
Частые вопросы о входящих вебхуках
Чем входящий вебхук отличается от исходящего?
Входящий вебхук позволяет внешней системе вызвать метод REST API Битрикс24 по секретному адресу. Исходящий отправляет событие из Битрикс24 на URL обработчика. Для реакции на событие и последующего чтения данных могут понадобиться оба механизма.
Нужно ли выбрать scope для метода profile?
Нет. В официальной инструкции profile используется для первой проверки без параметров и отдельного scope. Для метода CRM выберите scope crm и проверьте права владельца вебхука на нужный объект.
Почему profile работает, а метод CRM возвращает отказ?
profile проверяет саму авторизацию. Метод CRM дополнительно зависит от выбранного scope, прав сотрудника на запись, доступности REST API и условий метода. Читайте error_description вместе с кодом ошибки.
Можно ли вставить адрес вебхука в код сайта или отправить подрядчику в чат?
Полный URL содержит секрет. Храните его в защищённом серверном хранилище и выдавайте доступ только исполнителям, которым он нужен. Если код оказался публичным, перегенерируйте его и замените URL в интеграции.
Подойдёт ли входящий вебхук для тиражного приложения?
Для решения, которое устанавливают на разные порталы Битрикс24, используется приложение с OAuth 2.0. Часть методов требует контекста приложения и не вызывается через вебхук.
Официальная документация проверена 30 октября 2026 года. Снимки интерфейса и вызовы на клиентском портале для статьи не выполнялись; доступность REST и прав проверяйте в своём Битрикс24.