Розробка інтеграції Бітрікс24 через вебхуки: надійна архітектура

Найчастіша скарга на вебхук-інтеграції з Бітрікс24: «все працювало, а потім перестало». Причина майже завжди одна — обробник почав відповідати повільніше за 5 секунд, Бітрікс24 перестав його викликати, і ніхто цього не помітив, тому що логів не було. Ми проєктуємо відмовостійкі інтеграції вже понад 10 років — наші рішення витримують пікові навантаження чорної п’ятниці та обробляють до 1000 подій на хвилину. Якщо вам потрібна інтеграція під ключ, яка не впаде в найвідповідальніший момент — зв'яжіться з нами для консультації. Вартість типової інтеграції починається від $2000 за базовий сценарій і може сягати $10,000 для складних систем. Економія від автоматизації — до 80% часу на обробці заявок, що за рік може становити понад $15,000. Наприклад, при 1000 угод на місяць економія може бути $5,000 на рік.

Як організувати моніторинг доставки вебхуків?

Розглянемо як працюють вебхуки Бітрікс24. Вони функціонують у двох напрямках. Вихідний вебхук — Бітрікс24 викликає ваш URL при події. Підписка налаштовується в розділі «Розробникам» або через event.bind в REST API. Бітрікс24 робить POST-запит з Content-Type: application/x-www-form-urlencoded. Вхідний вебхук — ваша система викликає Бітрікс24 через фіксований URL з токеном. Зручно для простих односторонніх інтеграцій без OAuth. Для двосторонньої інтеграції ми зазвичай використовуємо обидва типи: вхідний для відправлення даних в Бітрікс24, вихідний — для отримання подій. Наша архітектура з чергою та дедуплікацією у 3 рази надійніша за просту HTTP-відповідь без черги, а швидкість обробки з Redis у 10 разів вища ніж у SQL-черги. Інтеграція через вебхуки в 5 разів швидша за періодичне опитування API.

Як підписатися на події через API?

Програмна підписка надійніша за ручне налаштування в інтерфейсі — не залежить від дій адміністратора і легше масштабується. Приклад підписки через REST API Бітрікс24:

// Підписка через REST API (від імені OAuth-застосунку) $b24->call('event.bind', [ 'event' => 'ONCRMDEALUPDATE', 'handler' => 'https://your-system.com/webhooks/bitrix24', 'auth_type' => 0, ]); 

Для відписки використовуйте event.unbind. Отримати список активних підписок можна через event.get.

Обробка подій: негайна відповідь та ідемпотентність

Структура вхідного запиту

Тіло POST-запиту від Бітрікс24 містить подію, handler_id, токени та самі дані. Важливо: data[FIELDS] містить лише змінені поля, а не повний об'єкт. Для отримання актуального стану угоди потрібен окремий виклик crm.deal.get.

auth[application_token] — токен для верифікації автентичності джерела запиту. Для коробкового Бітрікс24 перевіряємо його збіг з токеном застосунку.

Черга — обов'язковий патерн

Ключова вимога: обробник має повернути HTTP 200 протягом 5 секунд. Все, що довше — таймаут. Ми використовуємо чергу (наприклад, Laravel Queue) для асинхронної обробки повідомлень. Ось мінімальна реалізація:

// routes/api.php (Laravel) Route::post('/webhooks/bitrix24', function (Request $request) { // Валідація токена — швидко if (!validateBitrixToken($request->input('auth.application_token'))) { return response('Forbidden', 403); } // Кладемо в чергу — швидко ProcessBitrixEvent::dispatch($request->all()); // Негайно відповідаємо return response('OK', 200); }); // app/Jobs/ProcessBitrixEvent.php class ProcessBitrixEvent implements ShouldQueue { public $tries = 3; public $backoff = [60, 300, 900]; // 1 хв, 5 хв, 15 хв public function handle(): void { $event = $this->payload['event']; $dealId = $this->payload['data']['FIELDS']['ID']; // Тепер отримуємо повний об'єкт $deal = $this->b24->call('crm.deal.get', ['id' => $dealId]); // ... обробка } } 

Важливість ідемпотентності обробника

Одна подія може прийти двічі: Бітрікс24 повторює виклик при мережевих проблемах, а масові операції генерують ONCRMDEALUPDATE на кожне поле. Обробник має бути ідемпотентним. Приклад дедуплікації через Redis:

// Дедуплікація через event_handler_id + часова мітка $eventKey = md5($event . $dealId . $request->input('ts')); if ($redis->set("processed:{$eventKey}", 1, ['NX', 'EX' => 3600])) { ProcessBitrixEvent::dispatch($payload); // Якщо ключ вже є — дубль, ігноруємо } 

Бітрікс24 очікує HTTP 200 протягом 5 секунд. — документація REST API

Вхідний вебхук використовується для надсилання даних у Бітрікс24, вихідний — для отримання подій. — офіційна документація

Уникнення петлі синхронізації

Класична проблема: зовнішня система отримує подію ONCRMDEALUPDATE, оновлює дані у своїй БД, потім надсилає оновлення назад у Бітрікс24 — це знову генерує ONCRMDEALUPDATE, і цикл повторюється нескінченно. Ми застосовуємо три рішення для забезпечення транзакційної консистентності:

Прапорець в угоді

Встановлюємо кастомне поле UF_CRM_SYNC_LOCK=Y перед записом із зовнішньої системи, перевіряємо його в обробнику — якщо Y, пропускаємо і скидаємо.

Хеш даних

Порівнюємо хеш вхідних даних з останнім обробленим — якщо збігається, пропускаємо.

Часова мітка

Якщо подія про наше ж оновлення (час ≤ 2 сек з моменту нашого запису) — ігноруємо.

Моніторинг доставки та обмеження подій

Журнал подій та алерти

Бітрікс24 не веде журнал доставки вебхуків для зовнішніх отримувачів. Потрібно вести його самостійно. Ми створюємо таблицю для вебхуків:

CREATE TABLE webhook_events ( id SERIAL PRIMARY KEY, event_type VARCHAR(64), entity_id INTEGER, received_at TIMESTAMP DEFAULT NOW(), processed_at TIMESTAMP, status VARCHAR(16) DEFAULT 'pending', error_message TEXT ); 

Алерт: якщо за 10 хвилин у робочий час не приходить жодної події ONCRMDEALUPDATE, швидше за все, Бітрікс24 перестав викликати обробник. Отримайте консультацію з налаштування моніторингу у наших інженерів — ми допоможемо налаштувати алерти та дашборди. Для забезпечення eventually consistency використовуйте патерн Outbox.

Особливості подій

Важливо розуміти, що події CRM мають різну поведінку. У таблиці нижче наведено ключові нюанси:

Коробковий Бітрікс24: розширення подій

На коробці доступні події PHP-рівня, яких немає в REST API. Наприклад, можна перехопити подію до збереження угоди і змінити дані:

\Bitrix\Main\EventManager::getInstance()->addEventHandler( 'crm', 'OnBeforeCrmDealAdd', [MyHandler::class, 'onBeforeDealAdd'] ); 

Можна створювати свої події з модуля: $event = new \Bitrix\Main\Event(...). Надійний обробник вебхуків повинен використовувати чергу подій для асинхронної обробки. Інтеграція забезпечує автоматизацію бізнес-процесів.

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

Ми пропонуємо повний комплект послуг під ключ:

• Документація з архітектури
• Код endpoint-ів з використанням Redis та черг
• Налаштування черг та моніторингу (Grafana + Prometheus)
• Інструкція з розгортання та CI/CD
• Навчання вашої команди (воркшоп 2 години)
• Підтримка після запуску протягом 3 місяців
• Гарантія стабільної роботи, підтверджена сертифікатами партнера 1С-Бітрікс

Наша команда має 10+ років досвіду з Бітрікс24, виконала 50+ інтеграцій, має сертифікати партнера. Ми працюємо на ринку вже 10 років.

Етапи розробки та вартість

Покроковий план інтеграції

1. Проєктування: визначаємо список подій, схему даних, архітектуру обробника.
2. Endpoint і черга: реалізуємо HTTP-обробник, Job, дедуплікацію.
3. Бізнес-логіка: обробка кожного типу події, виклик зовнішніх систем.
4. Захист від циклів: прапорці синхронізації, idempotency.
5. Моніторинг: журнал подій, алерти, дашборд.
6. Тестування: емуляція подій, навантажувальні тести.

Сумарно: від 3 до 7 тижнів залежно від кількості подій та складності бізнес-логіки. Вартість розробки визначається після аналізу обсягу та складності — замовте оцінку за 1 день. Інтеграція дозволяє автоматизувати бізнес-процеси та підвищити ефективність роботи. Економія від автоматизації — до 80% часу на обробці заявок — окупає інтеграцію в розумний термін.

Замовте оцінку вашого проєкту — наші інженери проаналізують вашу архітектуру за один день і запропонують оптимальне рішення. Зв'яжіться з нами, щоб обговорити деталі.