Розробка вебхуків для Бітрікс24
Угода переходить у статус «Оплачено» — через кілька секунд в обліковій системі з'являється рахунок, у логістичній платформі створюється заявка на доставку, клієнту надходить SMS. Без вебхуків це була б ручна робота або polling-цикл із перевіркою змін кожну хвилину. Вебхуки — це push-сповіщення від Бітрікс24 про події в системі. Наша компанія має понад 5 років досвіду та реалізувала 50+ успішних інтеграцій. Ми, як розробники з 5+ річним досвідом, гарантуємо надійну реалізацію таких сценаріїв.
У середньому на один портал надходить 50-100 подій на хвилину в пік. Обробка кожної в реальному часі критична для бізнес-процесів. Без правильно налаштованої системи вебхуків компанії стикаються із затримками в доставці замовлень, дублюванням рахунків і втратою даних. Ми вирішуємо цю проблему за допомогою перевірених архітектурних патернів і стеку Бітрікс24.
Які проблеми вирішують вебхуки для Бітрікс24?
Вебхуки автоматизують реакцію на події без участі людини. Основні бізнес-завдання:
- Синхронізація угод CRM з обліковою системою (1С, ERP)
- Автоматичне створення замовлень у логістиці (Нова Пошта, Укрпошта)
- Відправка сповіщень клієнтам (SMS, email, Telegram)
- Оновлення даних в аналітичних дашбордах
З практики: на одному з проєктів інтеграція з 1С вимагала обробки 200 подій на хвилину. Ми реалізували асинхронну обробку через RabbitMQ і досягли часу обробки менше 1 секунди. Це в 10 разів швидше, ніж періодичний опитування (polling), яке давало затримку 30-60 секунд. Вебхуки краще за polling у 10 разів за швидкістю обробки.
Вхідні та вихідні вебхуки: ключові відмінності
У Бітрікс24 два типи вебхуків, які часто плутають:
| Тип | Напрямок | Аутентифікація | Приклад використання |
|---|---|---|---|
| Вихідний (Outbound) | Бітрікс24 → Ваш сервер | OAuth або токен у тілі | Реакція на подію CRM |
| Вхідний (Inbound) | Зовнішня система → Бітрікс24 | Токен в URL | Проста інтеграція без OAuth |
Вихідні вебхуки налаштовуються через інтерфейс або REST API event.bind. Вхідні вебхуки — це URL з вбудованим токеном, які можна використовувати для виклику REST API Бітрікс24 без повноцінного OAuth-потоку. Вибір типу залежить від сценарію: вихідні — для реакції на події, вхідні — для зовнішнього управління зі сторонніх систем.
Як налаштувати обробник вебхука?
Покроковий процес налаштування обробника:
- Зареєструйте підписку через
event.bindіз зазначенням події та URL обробника. - Реалізуйте endpoint, який приймає POST-запити від Бітрікс24.
- Верифікуйте підпис (перевірте токен авторизації та IP-адресу).
- Передайте дані в асинхронний обробник (через чергу).
- Поверніть HTTP 200 OK якомога швидше.
Приклад підписки на зміну стадії угоди:
Приклад коду підписки
$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 місяця після здачі
Терміни та вартість
| Масштаб | Склад | Термін | Вартість |
|---|---|---|---|
| Базовий | 2–3 типи подій + черга + логування | 2–3 тижні | від 15 000 грн |
| Середній | + верифікація + моніторинг + replay + кілька систем | 4–6 тижнів | від 35 000 грн |
| Розширений | + оркестрація складних сценаріїв + SLA-контроль | 7–10 тижнів | від 70 000 грн |
Впровадження вебхуків дозволяє заощадити до 200 годин ручної роботи на місяць, що еквівалентно 40 000 грн. Перед розробкою складаємо карту подій: яка подія Бітрікс24 -> яка дія в зовнішній системі. Це дозволяє оцінити обсяг роботи та виявити потенційні конфлікти.
Типові помилки при розробці вебхуків
- Відсутність ідемпотентності → дублювання даних
- Синхронна обробка → таймаути та повторні запити
- Ігнорування верифікації підпису → вразливість для підроблених запитів
- Недостатнє логування → складно налагоджувати збої
Вебхуки — ефективний інструмент для інтеграції, що працює в реальному часі та не вимагає polling. Вони порівняні з патерном Webhook.
Зв'яжіться з нами для оцінки вашого проєкту — ми запропонуємо оптимальне рішення під ключ. Досвід 5+ років і понад 50 успішних інтеграцій гарантують якість. Замовте розробку вебхуків і отримайте готове рішення за 2–3 тижні.