Вебхук и приложение — два способа доступа к REST API Битрикс24, и выбор между ними определяет всю архитектуру интеграции. Разберём, чем они принципиально различаются по авторизации, масштабу и возможностям, и дадим чёткие критерии, что выбрать под вашу задачу.
Суть различия
Оба способа обращаются к одному и тому же REST API, но модель доступа у них разная:
- Вебхук — секретный URL с постоянным кодом, привязанный к одному порталу и одному пользователю. Никакого OAuth, обмена токенами и установки.
- Приложение — программа, которая устанавливается на портал, авторизуется по OAuth 2.0 и может встраиваться в интерфейс, обрабатывать события и работать на многих порталах.
Проще говоря: вебхук — это ключ, а приложение — это программа, которую пользователь устанавливает и которой выдаёт доступ.
Таблица сравнения
| Критерий | Вебхук | Приложение |
|---|---|---|
| Авторизация | Секретный код в URL | OAuth 2.0 (access/refresh token) |
| Срок действия доступа | Пока не отозван вручную | Токен ~1 час, авто-обновление |
| Масштаб | Один портал | Один или множество порталов |
| От чьего имени | Владелец вебхука | Установивший пользователь |
| Встройки в интерфейс | Нет | Да (placement) |
| Обработка событий | Только исходящие вебхуки | Полноценные offline-события |
| Публикация в Маркетплейсе | Нет | Да |
| Скорость запуска | Минуты | Требует backend и разработки |
Когда выбирать вебхук
Вебхук — правильный выбор, когда задача проста и локальна:
- Интеграция одного своего портала — обмен с 1С, сайтом, внутренним сервисом.
- Разовые и служебные скрипты — миграция данных, массовое обновление, отчёт.
- Быстрый прототип — проверить гипотезу, не разворачивая инфраструктуру приложения.
- Серверный обмен без интерфейса — когда встройки в CRM не нужны.
Когда нужно приложение
Приложение обязательно, когда появляется хотя бы один из признаков:
- Тиражность — решение ставится на чужие порталы или продаётся в Маркетплейсе.
- Встройки в интерфейс — свои вкладки в карточке сделки, панель звонка, виджеты (placement).
- Действия от имени разных пользователей — важно, кто именно выполнил операцию.
- Сложные события — реакция на изменения через offline-события и обработчики.
- Требования безопасности — короткоживущие токены вместо вечного секрета.
Ценой за это становится необходимость backend, реализации OAuth и обработки установки — но без приложения перечисленные сценарии недостижимы.
Безопасность и сопровождение
Модели доступа несут разные риски и требуют разного сопровождения:
| Аспект | Вебхук | Приложение |
|---|---|---|
| Риск при утечке | Постоянный доступ до ручного отзыва | Токен истекает через час |
| Ротация секрета | Вручную (пересоздание) | Автоматически по refresh |
| Отзыв доступа | Удалить вебхук | Удалить приложение |
| Сложность кода | Низкая | Выше (OAuth, хранение токенов) |
Их можно комбинировать
Вебхук и приложение — не взаимоисключающие варианты. На одном портале нормально уживаются оба:
- Приложение обслуживает клиентский сценарий: встройки, действия пользователей, события.
- Вебхук закрывает внутренние служебные задачи: ночная выгрузка, интеграция с 1С, служебные скрипты.
Такой гибрид часто оптимален: не нужно тянуть всё через приложение там, где хватает простого вебхука, и наоборот — не городить костыли на вебхуках там, где нужна логика приложения.
Итог
Различие простое: вебхук — быстрый секретный ключ для одного портала без интерфейса, приложение — полноценная программа с OAuth, встройками и событиями для тиражных сценариев. Выбирайте вебхук для внутренней автоматизации и прототипов, приложение — когда нужны встройки, мультипортальность или действия от имени пользователей. А часто верный ответ — использовать оба под разные задачи.
Мы в B2Bsite помогаем выбрать модель под конкретный проект и реализуем её целиком: от простого вебхука для обмена с 1С до тиражного приложения с OAuth и встройками в CRM — с учётом безопасности, нагрузки и дальнейшего сопровождения.
Частые вопросы
Что быстрее запустить — вебхук или приложение?
Вебхук. Он создаётся за минуты в разделе «Разработчикам» без backend и OAuth. Приложение требует сервера, реализации авторизации и обработки установки.
Можно ли вебхуком сделать вкладку в карточке сделки?
Нет. Встройки в интерфейс (placement) доступны только приложению. Вебхук работает исключительно на уровне REST-запросов без UI.
Что безопаснее с точки зрения утечки?
Приложение. Его access_token живёт около часа и обновляется автоматически, тогда как код вебхука действует постоянно до ручного отзыва.
Нужно ли приложение для интеграции с 1С?
Обычно нет. Обмен одного портала с 1С удобно строить на входящем вебхуке. Приложение нужно, если решение тиражируется на другие порталы.
От чьего имени выполняются действия?
У вебхука — от имени его владельца. У приложения — от имени пользователя, который его установил, в рамках его прав.
Можно ли использовать вебхук и приложение вместе?
Да, это частая практика. Приложение обслуживает клиентские сценарии и встройки, а вебхук — внутренние служебные задачи вроде ночных выгрузок.
Когда переходить с вебхука на приложение?
Когда появляется тиражность, потребность во встройках, действиях от имени разных пользователей или обработке событий — эти сценарии вебхуку недоступны.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.