Главная / Блог / Вебхуки в Bitrix: связываем сервисы
← Вернуться к списку статей

Вебхуки в Bitrix: связываем сервисы

Опубликовано: 14.05.2026
★ ★ ★ ★ ★
Вебхуки в Bitrix: связываем сервисы

Что такое вебхуки в экосистеме Bitrix?

Вебхук — это механизм асинхронной коммуникации между сервисами. Когда в системе Bitrix происходит определённое событие (создание задачи, изменение карточки клиента, отправка письма), система отправляет HTTP-запрос на заранее заданный URL вашего сервера или стороннего сервиса.

Это позволяет разным системам работать как единый организм без необходимости писать сложную интеграционную логику вручную. Вебхуки стали стандартом де-факто для автоматизации в современных IT-архитектурах.

Как это работает технически

Весь процесс можно разделить на три этапа:

  1. Триггер события: в Bitrix происходит действие (например, менеджер поменял статус задачи).
  2. Генерация запроса: система формирует HTTP-запрос POST с JSON-телом и отправляет его на URL вебхука.
  3. Обработка: принимающий сервис получает данные, обрабатывает их и возвращает статус-код (обычно 200 — успех).

Важно: если сервер не отвечает в течение заданного таймаута, Bitrix может повторить отправку запроса несколько раз. Поэтому принимающий сервис должен быть устойчив к дублированию событий.

Подписка на события в Bitrix24

В Bitrix24 вебхуки создаются через интерфейс администратора или API. Основные шаги:

  1. Переходим в настройки интеграций платформы.
  2. Создаём новую подписку на событие (например, «Закреплено сообщение»).
  3. Указываем URL вашего обработчика (endpoint).
  4. Устанавливаем таймаут и количество повторных попыток.

После создания подписки Bitrix начинает отслеживать событие и отправлять данные на ваш сервер при каждом триггере.

Подписка на события в 1С-Битрикс

В движке Bitrix CMS подход аналогичен, но с учётом специфики платформы:

  1. Используем модуль «Вебхуки» (обычно включён по умолчанию).
  2. Зарегистрируем обработчик через код или административный интерфейс.
  3. Назначаем события, которые должны вызывать отправки.
  4. Настраиваем маршрутизацию: разные события могут идти на разные эндпоинты.

Важно помнить, что в CMS Bitrix вебхуки также используются для внутренней асинхронной обработки событий внутри движка. Например, при создании элемента инфоблока может срабатывать несколько внутренних обработчиков, которые вызывают внешние вебхуки.

Формат данных: JSON и сигнатуры

Bitrix отправляет данные в формате JSON. Структура зависит от типа события:

  • Задачи: id, title, status, assignee, created_date.
  • Мессенджер: message_id, text, from_user, to_users.
  • Сделки: deal_id, amount, stage, owner.

    • К каждому запросу Bitrix может прилагать подпись (signature) — хеш от таймстома и ключа подписи. Это позволяет принимающему сервису удостовериться в подлинности события. Для этого необходимо:

    1. Сформировать ожидаемую подпись на основе данных события.
    2. Сравнить её с подписью из заголовка запроса.
    3. Если совпадают — событие подлинное, если нет — отклонить.

    Игнорирование проверки подписи открывает возможность атак: злоумышленник может отправлять ложные события и вводить систему в заблуждение.

    Обработка событий: best practices

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

  • Идиоматичность: не блокируйте основной поток обработки запроса. Используйте асинхронные операции для длительных задач.
  • Обработка ошибок: логгируйте ошибки, возвращайте корректный статус-код и JSON с описанием проблемы.
  • Идентификация события: храните в базе ID события, чтобы не обрабатывать одно и то же событие дважды (idempotency).
  • Тестирование: используйте встроенные тестовые вебхуки Bitrix для отладки перед продакшеном.

    • Ограничения и подводные камни

    Вебхуки — мощный инструмент, но у него есть ограничения:

  • Таймаут по умолчанию в Bitrix24 составляет 30 секунд. Для долгих операций используйте асинхронную обработку.
  • В 1С-Битриксе количество одновременных вебхуков ограничено конфигурацией модуля.
  • При сбое сервиса Bitrix может отправить запрос повторно — ваш обработчик должен это учитывать.
  • Некоторые события (например, «удаление задачи») могут не иметь обратной связи — если обработчик упал, событие будет потеряно.

    • Альтернативы: API и очереди

    Вебхуки — это один из способов интеграции. В зависимости от задач можно выбрать:

  • REST API: подходит для синхронных запросов, когда клиент ждёт ответа.
  • OAuth2 + API: для доступа к данным с авторизацией пользователя.
  • Очерь событий (EventQueue): в Bitrix есть встроенная очередь событий, которая позволяет планировать отправки и гарантировать доставку.
  • Webhooks + ODBC/JDBC: для глубокой интеграции с базами данных.

    • Вывод

    Вебхуки в Bitrix — это эффективный способ связать вашу платформу с внешним миром. Они позволяют автоматизировать бизнес-процессы, снижать нагрузку на пользователей и создавать экосистему интегрированных сервисов. Однако важно правильно проектировать обработчики событий: учитывать ограничения, обеспечивать отказоустойчивость и проверять подлинность данных.

    Начните с тестовых вебхуков, проработайте обработку ошибок и постепенно расширяйте функционал — так вы получите надёжную архитектуру интеграции без риска потери данных.