Исходящий вебхук Битрикс24: как получить событие во внешней системе
Исходящий вебхук нужен, когда внешняя система должна узнать об изменении в Битрикс24. Вы выбираете событие и публичный адрес обработчика; Битрикс24 отправляет туда POST. Дальше ваша система проверяет отправителя и решает, нужны ли ей полные данные объекта.
Например, менеджер обновил сделку, а складская система должна начать проверку заказа. Исходящий вебхук передаст ей сигнал об изменении. Сам по себе сигнал не создаёт заказ в МойСклад и не переносит все поля сделки: дальнейшее действие задаёт ваша интеграция.
Что подготовить до создания вебхука
Нужен обработчик по публичному HTTPS-адресу, доступный Битрикс24 из интернета и принимающий POST-запросы. Локальный адрес, внутренний IP и самоподписанный сертификат для этого сценария не подходят. Заранее определите, какое изменение должно запускать интеграцию и где ваш сервер запишет факт получения.
В разделе «Разработчикам → Готовые сценарии → Другое → Исходящий вебхук» укажите адрес обработчика и выберите событие. Для проверки изменения сделки подойдёт ONCRMDEALUPDATE. После создания Битрикс24 покажет «Токен приложения»: сохраните его в защищённом серверном хранилище. В форму сайта, клиентский JavaScript и скриншоты токен не переносите.
Если пункт создания недоступен, проверьте право пользователя и условия доступа к вебхукам в вашем Битрикс24. Справка Битрикс24 указывает на подписку BitrixGPT + Маркетплейс для создания вебхуков; на деморежиме исходящий вебхук недоступен, а коробочной версии нужна активная лицензия. Вкладка «Интеграции» показывает созданные вебхуки, выбранные события и владельца.
Что получает внешняя система
Битрикс24 отправляет параметры события POST-запросом с типом application/x-www-form-urlencoded. В примере ONCRMDEALUPDATE сырой ключ формы data[FIELDS][ID] содержит ID обновлённой сделки; после разбора формы его обычно читают как data.FIELDS.ID. Аналогично передаются ключи auth[member_id] и auth[application_token]. Дату отправки передаёт ts. Полной карточки и списка изменённых полей в событии нет: если они нужны, обработчик после проверки запроса получает сделку отдельным авторизованным вызовом REST.
| Поле | Смысл | Проверка |
|---|---|---|
| event | Код события, например ONCRMDEALUPDATE | Проверить, на то ли действие подписан вебхук |
| data[FIELDS][ID] | ID изменённой сделки | Найти ту же карточку в CRM; полные поля читать отдельно |
| auth[member_id] | Идентификатор портала | Соотнести событие с сохранённым токеном этого портала |
| auth[application_token] | Токен проверки отправителя | Сравнить на сервере, не выводить в журнал |
После разбора формы auth.application_token — общий секрет для проверки источника, а не криптографическая подпись тела запроса. Сопоставляйте токен с нужным порталом по auth.member_id. Не записывайте секрет в обычный журнал. Если токен не совпал, не выполняйте бизнес-действие и верните отказ.
Как проверить доставку на одной сделке
Создайте или выберите безопасную тестовую карточку. Запишите её ID и время проверки, измените одно несекретное поле и сохраните. На своём сервере найдите запрос с событием ONCRMDEALUPDATE и тем же data.FIELDS.ID. Сравните токен, убедитесь, что запрос надёжно сохранён, и проверьте итог действия во внешней системе. Если действие должно выполняться только при определённой стадии или значении поля, после чтения полной карточки проверьте это условие: одно уведомление ONCRMDEALUPDATE не сообщает, какое поле изменилось.
Тяжёлую обработку лучше выполнять после приёма: сначала поместить проверенное событие в надёжный журнал или очередь, затем ответить Битрикс24 успехом. Документация прямо предупреждает, что при отсутствии ответа или аварийном HTTP-статусе Битрикс24 не отправляет событие повторно. Внутренний рабочий процесс может повторно взять сохранённый запрос после сбоя, поэтому его действие должно выдерживать повторную обработку без дублирования заказа.
Если событие не дошло
Если в журнале приёма нет запроса, начните с адреса: он должен открываться из внешней сети по HTTPS, принимать POST и отвечать сервером обработчика. Затем проверьте, тот ли вебхук сохранён, выбран ли нужный код события и произошло ли контрольное изменение. Для коробочного Битрикс24 дополнительно проверьте необходимые сетевые доступы.
Если запрос есть, но внешняя система не изменилась, смотрите результат проверки токена, сохранение события, состояние своей очереди и ошибку последующего вызова REST. Статистика раздела «Разработчикам» помогает оценить REST-запросы и нагрузку, но не заменяет ваш журнал приёма событий. Список интеграций подтверждает настройку вебхука, но не приём события вашим сервером.
Для двустороннего обмена может понадобиться входящий вебхук или приложение с OAuth 2.0. Если ваша цель — перенести данные из CRM в МойСклад, сначала зафиксируйте событие, поля и правило сопоставления записей; общий разбор есть в статье об интеграции Битрикс24 и МоегоСклада.
Частые вопросы об исходящем вебхуке Битрикс24
Чем исходящий вебхук отличается от входящего?
Исходящий вебхук уведомляет ваш обработчик о событии в Битрикс24. Входящий вебхук даёт внешней системе вызвать метод REST API Битрикс24. Если после сигнала нужны полные данные сделки, обработчику потребуется отдельный авторизованный запрос.
Что приходит при изменении сделки?
Для ONCRMDEALUPDATE документация показывает POST с кодом события, временем отправки, служебными данными auth и ID сделки в data.FIELDS.ID. Полную карточку из этого уведомления получить нельзя; запросите её через подходящий метод REST при необходимости.
Как проверить, что запрос действительно от Битрикс24?
После создания исходящего вебхука сохраните «Токен приложения» на сервере. При получении события сопоставьте auth.member_id с нужным порталом и сравните auth.application_token с сохранённым значением. При несовпадении отклоните запрос. Это проверка токена, а не подписи тела запроса.
Битрикс24 повторит событие, если наш сервер был недоступен?
По документации Битрикс24 не отправляет событие повторно, если обработчик не ответил или вернул аварийный HTTP-статус. Поэтому сначала надёжно сохраните принятое событие на своём сервере, а только потом ответьте успехом. Повторную обработку после сбоя своего рабочего процесса организуйте в собственной очереди.
Где посмотреть, дошло ли событие?
Начните с журнала приёма на своём сервере: время, код события, ID объекта, итог проверки токена и статус сохранения без секретов. Если записи нет, проверьте публичность HTTPS-адреса, выбранное событие и отклик обработчика на контрольное изменение сделки. Статистика REST в Битрикс24 не заменяет журнал доставки вашего обработчика.
Можно ли указать localhost или адрес внутри сети?
Нет. Битрикс24 должен достучаться до обработчика из внешней сети. Укажите публичный HTTPS-адрес с доверенным сертификатом и принимающий POST сервер. Для закрытого контура также проверьте сетевые правила.
Официальная документация Битрикс24 проверена 1 ноября 2026 года. Схемы составлены редакцией по документации; создание вебхука и доставка на клиентском портале для этой статьи не тестировались.