Розробка вебхуків для Бітрікс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 → яка дія у зовнішній системі. Це дозволяє оцінити обсяг роботи та виявити потенційні конфлікти (одна подія запускає ланцюжок дій).