Входящий вебхук: быстрый старт

Входящий вебхук — это персональный секретный URL, через который внешняя система обращается к REST API Битрикс24 от имени одного пользователя. Это самый быстрый способ подключиться: без OAuth, регистрации приложения и обмена токенами. Разберём, как его создать и сделать первый вызов.

Что такое входящий вебхук

Входящий (incoming) вебхук принимает запросы снаружи внутрь портала: ваш сервер шлёт HTTP-запрос на секретный URL, а Битрикс24 выполняет метод API. Не путайте с исходящим (outgoing) вебхуком — тот, наоборот, сам уведомляет ваш сервер о событиях (например, о создании сделки).

• Входящий — «я хочу что-то сделать в портале»: создать лид, прочитать сделки, поставить задачу.
• Исходящий — «портал сообщает мне о событии»: сработал ONCRMDEALADD, ушёл POST на мой обработчик.

Вебхук работает от имени того сотрудника, который его создал, и наследует его права плюс явно выданный scope. Это удобно для внутренних интеграций одного портала.

Как создать вебхук в портале

Создание занимает минуту и не требует программирования:

1. Откройте левое меню портала → раздел «Разработчикам» (Developer resources).
2. Выберите «Другое» → «Входящий вебхук».
3. Отметьте нужные права доступа (scope): например, CRM, Пользователи (user), Задачи (task).
4. Сохраните — портал сгенерирует URL и код вебхука.

Из чего состоит URL вебхука

URL имеет строгую структуру. Разберём на примере:

https://mycompany.bitrix24.ru/rest/ 1 / xr9s7k3q0abcd12e / crm.deal.list .json
          домен портала        /rest/ ID   секретный код     метод      формат

Имя метода — часть адреса, поэтому один вебхук вызывает любой метод в рамках выданного scope: просто подставляйте нужное имя вместо crm.deal.list.

Первый запрос

Проверьте доступ безопасным методом чтения — profile возвращает данные владельца вебхука:

curl "https://mycompany.bitrix24.ru/rest/1/xr9s7k3q0abcd12e/profile.json"

Теперь создадим лид методом crm.lead.add через POST:

curl -X POST \
  "https://mycompany.bitrix24.ru/rest/1/xr9s7k3q0abcd12e/crm.lead.add.json" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"TITLE": "Заявка с лендинга", "NAME": "Иван", "PHONE": [{"VALUE": "+79001234567", "VALUE_TYPE": "WORK"}]}}'

// Ответ
{ "result": 47, "time": { "duration": 0.21 } }

Число в result — ID созданного лида. Если пришла ошибка INSUFFICIENT_SCOPE, значит вебхуку не выдано право crm — вернитесь в настройки и отметьте его.

Безопасность вебхука

Секретный код в URL — это фактически пароль. Утечка URL = полный доступ к данным в рамках scope. Базовые правила:

• Никогда не храните URL в открытом виде в клиентском коде, репозитории или логах. Только в переменных окружения / секрет-хранилище.
• Заводите отдельный вебхук на каждую интеграцию — так проще отозвать один, не ломая остальные.
• Ограничивайте scope до минимума под задачу.
• Создавайте вебхук от имени сервисного пользователя, а не директора: права наследуются от владельца.
• Отзывайте и пересоздавайте код при подозрении на компрометацию — старый URL сразу перестанет работать.

Ограничения и когда переходить на приложение

Вебхук закрывает 80% задач внутренней интеграции, но у него есть потолок:

Как только нужна установка на чужие порталы, встройки (placement) или действия от имени разных пользователей — переходите на приложение с OAuth 2.0.

Итог

Входящий вебхук — самый быстрый путь к REST API Битрикс24: создали в разделе «Разработчикам», выдали минимальный scope, подставили метод в URL и вызвали. Он идеален для интеграций одного портала: обмен с 1С, приём заявок с сайта, служебные скрипты. Главное — беречь секретный код как пароль и не выдавать лишних прав.

Когда обмен становится критичным для бизнеса, мы в B2Bsite оборачиваем вебхуки в надёжную интеграцию: очереди, повторы при сбоях, логирование и мониторинг, чтобы заявки и данные не терялись между системами.