При інтеграції CRM із зовнішнім сервісом часто виникає задача: отримувати сповіщення про нові угоди, ліди або дзвінки без постійного опитування API. Вебхуки вирішують це, надсилаючи HTTP-запит одразу після події. Як зазначено в документації Бітрікс24: вебхуки дозволяють отримувати сповіщення про події в реальному часі. За 10+ років ми налаштували такі механізми для 50+ проєктів: від сповіщень у Telegram до синхронізації з 1С. Нижче — технічні деталі, щоб уникнути типових помилок та заощадити до 40% часу на інтеграцію.
Два типи вебхуків
Вхідний вебхук (Inbound). Зовнішня система викликає Бітрікс24. Ви отримуєте фіксований URL виду https://domain.bitrix24.ru/rest/1/хеш_токена/метод.json і можете викликати будь-які REST-методи без OAuth-авторизації. Використовується для надсилання даних у Бітрікс24 із сторонніх систем.
Вихідний вебхук (Outbound). Бітрікс24 викликає зовнішню систему при настанні події. Ви підписуєтеся на конкретні події (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND та ін.) і вказуєте URL обробника. При настанні події Бітрікс24 POST-ом надсилає дані на цей URL.
Чому вихідні вебхуки ефективніші за полінг?
На відміну від полінгу, вебхуки працюють у реальному часі: подія → HTTP-запит за секунди. Це швидше за полінг у 10 разів і знижує навантаження на сервер. Для більшості сценаріїв (сповіщення, синхронізація) цього достатньо. Якщо потрібна гарантована доставка — використовуємо чергу та повторні спроби.
Як налаштувати вихідний вебхук під вашу задачу?
У розділі «Розробникам → Інше → Вихідний вебхук» виберіть подію зі списку. Основні події для CRM:
-
ONCRMLEADADD/ONCRMLEADUPDATE— лід створено / змінено -
ONCRMDEALADD/ONCRMDEALUPDATE/ONCRMDEALDELETE— угода -
ONCRMCONTACTADD/ONCRMCONTACTUPDATE— контакт -
ONCRMCOMPANYADD/ONCRMCOMPANYUPDATE— компанія -
ONCRMACTIVITYADD— додано справу (дзвінок, лист, зустріч) -
ONVOXIMPLANTCALLEND— завершено дзвінок (телефонія) -
ONTASKUPDATE— оновлення завдання
У полі «Адреса обробника» вкажіть URL зовнішнього сервісу. Бітрікс24 надсилає POST-запит із application/x-www-form-urlencoded тілом, що містить дані події.
| Подія | Тип | Приклад використання |
|---|---|---|
ONCRMDEALADD |
Угода | Сповіщення в Telegram про нову угоду |
ONVOXIMPLANTCALLEND |
Дзвінок | Запис дзвінка в сторонню CRM |
ONTASKUPDATE |
Завдання | Синхронізація статусу завдання із зовнішнім трекером |
Структура вхідного запиту
Тіло запиту від Бітрікс24 містить:
event=ONCRMDEALUPDATE &auth[access_token]=... &auth[domain]=domain.bitrix24.ru &data[FIELDS][ID]=12345 &data[FIELDS][STAGE_ID]=WON Поле data[FIELDS] містить змінені поля сутності. Для отримання повного стану об'єкта потрібно зробити окремий запит через REST API (crm.deal.get з id=12345), використовуючи токен з auth.
Обробник на стороні зовнішньої системи
Принципова вимога: обробник має відповісти HTTP 200 протягом кількох секунд. Якщо відповідь не надійшла або код відмінний від 2xx — Бітрікс24 вважає доставку невдалою. Повторних спроб за замовчуванням немає (на відміну від повноцінних застосунків із чергами подій).
Правильний патерн:
- Прийняти запит, відповісти 200
- Поставити задачу в чергу (Redis, RabbitMQ, БД)
- Обробити асинхронно
Приклад обробника на PHP
<?php // Отримуємо дані вебхука $data = $_POST; // Одразу відповідаємо 200 http_response_code(200); // Ставимо задачу в чергу (наприклад, через Redis) $redis->lpush('webhook_queue', json_encode($data)); Якщо обробка синхронна і займає більше 3–5 секунд — Бітрікс24 фіксує тайм-аут.
Які заходи безпеки необхідні?
Вебхук-endpoint публічно доступний з інтернету — це потрібно враховувати. Заходи захисту:
- Перевірка токена. В URL вхідного вебхука є токен — валідуємо його на стороні обробника
- IP-whitelist. Дозволяємо запити тільки з IP-адрес Бітрікс24 (список публікується в документації)
- HMAC-підпис. Для локальних застосунків доступний підпис запиту — перевіряємо заголовок
X-Bitrix-Hmac-Sha256
Обмеження та особливості
Вебхуки працюють в рамках лімітів REST API: 2 запити в секунду для хмарного Бітрікс24 (на вхідні вебхуки). При масових операціях (імпорт 1000 угод) кожне створення генерує подію — обробник має справлятися з піковим навантаженням.
Для коробкового Бітрікс24 ліміти вищі та налаштовуються у файлі /bitrix/.settings.php. Події обробляються синхронно в рамках того ж PHP-процесу, що створює навантаження при частих подіях.
| Аспект | Хмарний Бітрікс24 | Коробковий |
|---|---|---|
| Ліміт REST API | 2 запити/сек | Налаштовується |
| Повторні спроби | Немає | Немає (без додаткових рішень) |
| Список подій | Стандартний | Розширюється через AddEventHandler |
| Кастомні події | Тільки через застосунок | Через \Bitrix\Main\EventManager |
Типові помилки при налаштуванні вебхуків
- Синхронна обробка — призводить до тайм-аутів. Рішення: асинхронна черга.
- Ігнорування IP-фільтрації — endpoint вразливий для підроблених запитів.
- Відсутність логування — складно налагоджувати збої доставки.
Що входить в роботу?
- Аудит поточної архітектури та вибір типу вебхуків
- Налаштування вихідних/вхідних вебхуків з потрібними подіями
- Розробка обробника з асинхронною чергою (Redis, RabbitMQ)
- Документація по endpoints та безпеці
- Тестування під навантаженням та гарантія доставки
- Навчання вашої команди роботі з вебхуками
Вартість налаштування одного вебхука з обробником визначається індивідуально після аналізу вашої системи. Весь процес займає від 1 до 5 днів.
Якщо потрібна надійна інтеграція без втрати подій — зв'яжіться з нами. Оцінимо проєкт безкоштовно та запропонуємо оптимальне рішення. Замовте налаштування вебхуків під вашу архітектуру – отримайте гарантію доставки та безпеку.