Вебхуки Битрикс24: первый запрос и безопасная настройка
Как создать входящий или исходящий вебхук, выдать минимальные права, выполнить тест и не раскрыть секретный код.
Время чтения: 11 мин.
Уровень: Средний
Системные требования
Нужны права на создание интеграций и HTTPS. Входящий вебхук работает с правами создавшего его пользователя и выбранными scope.
Смотреть системные требования1. Выберите тип вебхука
- Входящий вебхук — ваша система вызывает методы Битрикс24.
- Исходящий вебхук — Битрикс24 отправляет событие вашему HTTPS-обработчику.
- OAuth-приложение — подходит для тиражируемой интеграции, нескольких порталов и управляемого обновления токенов.
Для одного внутреннего сценария обычно достаточно вебхука. Для продукта, который устанавливают разные клиенты, проектируйте приложение с OAuth.
Официальная REST-документация
Используйте актуальные методы, параметры и коды ошибок из документации Битрикс24.
2. Создайте входящий вебхук с минимальными правами
Откройте Приложения → Разработчикам → Готовые сценарии → Другое → Входящий вебхук. Выберите только те права, которые нужны интеграции.
Создавайте отдельный вебхук для отдельной системы и технического пользователя с ограниченными правами. Так проще отключить доступ и определить источник изменения данных.
Совет
Код вебхука — пароль. Не вставляйте реальный URL в браузерный JavaScript, публичный репозиторий, скриншот или журнал. При утечке сразу удалите вебхук и создайте новый.
3. Выполните безопасный тест
Сначала используйте метод чтения, например получение профиля текущего пользователя. В команде ниже замените placeholders, но не сохраняйте реальный код в истории shell:
curl -sS -X POST https://PORTAL.example/rest/USER_ID/WEBHOOK_CODE/profile.jsonПроверяйте HTTP-статус и JSON-поля error и error_description. Только после успешного чтения переходите к методам изменения данных.
4. Проверьте исходящий вебхук
Обработчик должен быть доступен из интернета по HTTPS и принимать POST-запросы. Для коробочного Битрикс24 проверьте сетевые правила и сертификат.
Сравнивайте auth[application_token] с токеном из настройки исходящего вебхука. Не доверяйте только IP или имени события. Если нужны полные данные объекта, получите их отдельным REST-запросом по переданному ID.
Официальная документация по входящим и исходящим вебхукам.
5. Обрабатывайте ошибки и лимиты
Записывайте в технический журнал имя метода, HTTP-статус, error, error_description и идентификатор запроса. Не записывайте токены и полный URL вебхука.
При временном лимите используйте задержку и повтор с увеличением интервала. Ошибки доступа, scope и неверной авторизации повтором не исправляются — сначала измените права или учётные данные.
Официальные коды ошибок REST API.
Была ли эта статья полезной?
Спасибо за ваш отзыв!
