Разработка вебхуков для Битрикс24

Разработка вебхуков для Битрикс24

Сделка переходит в статус «Оплачено» — и через несколько секунд в учётной системе появляется счёт, в логистической платформе создаётся заявка на доставку, а клиенту уходит SMS. Без вебхуков это было бы либо ручной работой, либо polling-циклом, который проверяет изменения каждую минуту. Вебхуки — это push-уведомления от Битрикс24 о событиях, произошедших в системе.

Входящие vs исходящие вебхуки

В Битрикс24 два типа вебхуков, которые часто путают:

Исходящие вебхуки (Outbound webhooks). Битрикс24 отправляет HTTP-запрос на ваш сервер при наступлении события. Настраиваются через интерфейс или через REST API event.bind. Это основной инструмент для реакции на события CRM.

Входящие вебхуки (Inbound webhooks). Внешний сервис вызывает REST API Битрикс24 без OAuth — по URL с встроенным токеном. Используются для простых интеграций, где не нужен полный OAuth-поток.

Настройка исходящих вебхуков через REST API

// Подписка на событие изменения статуса сделки
$client->call('event.bind', [
    'event'     => 'ONCRMDEALSTAGEID',
    'handler'   => 'https://integration.mycompany.ru/b24/webhook/deal-stage',
    'auth_type' => 1,          // передавать токен авторизации
    'options'   => [
        'add_auth' => 'Y',
    ],
]);

Полный список событий CRM: ONCRMDEALCHANGE, ONCRMCONTACTCHANGE, ONCRMLEADCHANGE, ONCRMACTIVITYCHANGE и др. — более 150 событий в документации.

Детально: обработчик вебхука на стороне приложения

Обработчик должен ответить на запрос Битрикс24 быстро (до 5 секунд) и обработать данные асинхронно. Если обработчик отвечает медленно или возвращает не 200 OK — Битрикс24 повторяет запрос несколько раз с экспоненциальным backoff.

// Маршрут POST /b24/webhook/deal-stage
public function handleDealStage(Request $request): Response
{
    // 1. Верифицировать подпись (если настроена)
    if (!$this->verifySignature($request)) {
        return response('Unauthorized', 401);
    }

    // 2. Добавить задачу в очередь и сразу ответить 200
    DealStageChangedJob::dispatch($request->all())->onQueue('b24-events');

    return response('OK', 200);
}

// 3. Задача обрабатывается асинхронно
class DealStageChangedJob implements ShouldQueue {
    public function handle(): void {
        $dealId  = $this->data['data']['FIELDS_AFTER']['ID'];
        $stageId = $this->data['data']['FIELDS_AFTER']['STAGE_ID'];

        if ($stageId === 'WON') {
            // Создать счёт в учётной системе
            $this->accountingService->createInvoice($dealId);
            // Создать заявку в логистике
            $this->logisticsService->createShipment($dealId);
            // Отправить SMS клиенту
            $this->smsService->sendPaymentConfirmation($dealId);
        }
    }
}

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

Верификация подписи

Битрикс24 может передавать в вебхуке токен авторизации (auth[access_token]). Обработчик должен проверить, что токен принадлежит ожидаемому порталу и приложению. Для дополнительной безопасности можно добавить IP-whitelist — Битрикс24 публикует список своих IP-адресов.

Хранение и мониторинг

Все входящие вебхуки логируются в таблице myvendor_b24_webhook_log:

• время получения
• тип события
• тело запроса (с маскированием токенов)
• статус обработки (pending / processed / failed)
• количество попыток

Dashboard мониторинга показывает: очередь необработанных событий, события с ошибками, среднее время обработки. При накоплении более 50 необработанных событий — алерт на email/Telegram администратору.

Паттерн replay

При сбое внешней системы (например, учётная система была недоступна) часть вебхуков могла не обработаться. Модуль реализует возможность повторной обработки: администратор выбирает диапазон дат и тип события, система заново выполняет обработчик для всех событий из лога.

Сроки разработки

Перед разработкой составьте карту событий: какое событие Битрикс24 → какое действие во внешней системе. Это позволяет оценить объём работы и выявить потенциальные конфликты (одно событие запускает цепочку действий).