Розробка вебхуків для Бітрікс24: налаштування, обробка та інтеграція

$client->call('event.bind', [
    'event' => 'ONCRMDEALSTAGEID',
    'handler' => 'https://integration.mycompany.ru/b24/webhook/deal-stage',
    'auth_type' => 1,
    'options' => [
        'add_auth' => 'Y',
    ],
]);

Повний список доступних подій CRM включає понад 150 найменувань: ONCRMDEALCHANGE, ONCRMCONTACTCHANGE, ONCRMLEADCHANGE та інші. Ознайомитись із переліком можна в офіційній документації REST API.

Чому важлива ідемпотентність?

Обробник вебхука має відповідати швидко (до 5 секунд) і обробляти дані асинхронно. Якщо відповідь повільна або не 200 OK — Бітрікс24 повторює запит з експоненційним backoff. Без ідемпотентності повторна обробка створить дублі: наприклад, подвійний рахунок або два замовлення на доставку. Ідемпотентність гарантує, що повторні виклики не призведуть до побічних ефектів.

public function handleDealStage(Request $request): Response
{
    if (!$this->verifySignature($request)) {
        return response('Unauthorized', 401);
    }

    DealStageChangedJob::dispatch($request->all())->onQueue('b24-events');

    return response('OK', 200);
}

class DealStageChangedJob implements ShouldQueue
{
    public function handle(): void
    {
        $dealId = $this->data['data']['FIELDS_AFTER']['ID'];
        $stageId = $this->data['data']['FIELDS_AFTER']['STAGE_ID'];

        // Перевірка ідемпотентності: подію вже оброблено?
        if ($this->alreadyProcessed($dealId, $this->data['event_id'])) {
            return;
        }

        if ($stageId === 'WON') {
            $this->accountingService->createInvoice($dealId);
            $this->logisticsService->createShipment($dealId);
            $this->smsService->sendPaymentConfirmation($dealId);
        }
    }
}

Як забезпечити надійність системи?

Верифікація підпису.

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

Зберігання та моніторинг.

Усі вхідні вебхуки логуються в таблиці vendor_b24_webhook_log:

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

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

Патерн replay.

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

Що входить в роботу

При замовленні розробки вебхуків ви отримуєте:

• Карту подій: аналіз бізнес-процесів і прив'язка до подій Бітрікс24
• Розробку обробників (endpoint + асинхронна черга)
• Налаштування логування та моніторингу
• Документацію з розгортання та експлуатації
• Навчання адміністраторів (1 година)
• Технічну підтримку протягом 1 місяця після здачі

Терміни та вартість

Впровадження вебхуків дозволяє заощадити до 200 годин ручної роботи на місяць, що еквівалентно 40 000 грн. Перед розробкою складаємо карту подій: яка подія Бітрікс24 -> яка дія в зовнішній системі. Це дозволяє оцінити обсяг роботи та виявити потенційні конфлікти.

Типові помилки при розробці вебхуків

• Відсутність ідемпотентності → дублювання даних
• Синхронна обробка → таймаути та повторні запити
• Ігнорування верифікації підпису → вразливість для підроблених запитів
• Недостатнє логування → складно налагоджувати збої

Вебхуки — ефективний інструмент для інтеграції, що працює в реальному часі та не вимагає polling. Вони порівняні з патерном Webhook.

Зв'яжіться з нами для оцінки вашого проєкту — ми запропонуємо оптимальне рішення під ключ. Досвід 5+ років і понад 50 успішних інтеграцій гарантують якість. Замовте розробку вебхуків і отримайте готове рішення за 2–3 тижні.