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

Налаштування вебхуків для зовнішніх інтеграцій Bitrix24

Вебхук — механізм, при якому Bitrix24 сам повідомляє зовнішню систему про подію, не змушуючи її постійно опитувати API. Нова угода, зміна стадії, вхідний дзвінок — Bitrix24 відправляє HTTP-запит на вказаний URL протягом кількох секунд. Це основний інструмент для побудови інтеграцій без розробки повнофункціонального додатку.

Два типи вебхуків

Вхідний вебхук (Inbound webhook). Зовнішня система викликає Bitrix24. Ви отримуєте фіксовану URL виду https://domain.bitrix24.ru/rest/1/хеш_токена/метод.json і можете викликати будь-які REST-методи без OAuth-авторизації. Використовується для відправки даних у Bitrix24 з третіх сторін.

Вихідний вебхук (Outbound webhook). Bitrix24 викликає зовнішню систему при настанні подіїі. Ви підписуєтесь на конкретні події (ONCRMDEALADD, ONCRMDEALUPDATE, ONVOXIMPLANTCALLEND та ін.) та вказуєте URL обробника. При настанні події Bitrix24 POST-ом відправляє дані на цю URL.

Налаштування вихідного вебхука

У розділі «Розробникам → Інше → Вихідний вебхук» виберіть подію зі списку. Основні eventi для CRM:

• ONCRMLEADADD / ONCRMLEAD UPDATE — лід створений / оновлений
• ONCRMDEALADD / ONCRMDEALUPDATE / ONCRMDEALDELETE — угода
• ONCRMCONTACTADD / ONCRMCONTACTUPDATE — контакт
• ONCRMCOMPANYADD / ONCRMCOMPANYUPDATE — компанія
• ONCRMACTIVITYADD — додано справу (дзвінок, лист, зустріч)
• ONVOXIMPLANTCALLEND — завершено дзвінок (телефонія)
• ONTASKUPDATE — оновлення завдання

У полі «Адреса обробника» введіть URL зовнішнього сервісу. Bitrix24 відправляє POST-запит з application/x-www-form-urlencoded тілом, що містить дані événements.

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

Тіло запиту від Bitrix24 містить:

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—Bitrix24 вважає доставку невдалою. Повторних спроб за замовчуванням немає (на відміну від повнофункціональних додатків з чергами событий).

Правильний паттерн:

1. Прийняти запит, відповісти 200
2. Поставити завдання у чергу (Redis, RabbitMQ, БД)
3. Обробити асинхронно

Якщо обробка синхронна і займає більше 3–5 секунд—Bitrix24 записує timeout.

Безпека

Вебхук-endpointต публічно доступний з інтернету — це необхідно враховувати. Заходи защиты:

• Перевірка токену. В URL вхідного вебхука є токен — валідуйте його на стороні обробника
• IP-whitelist. Дозволяйте запити тільки з IP-адрес Bitrix24 (список опублікований у документації)
• HMAC-підпис. Для локальних додатків доступна підпис запиту — перевірте заголовок X-Bitrix-Hmac-Sha256

Обмеження та особливості

Вебхуки працюють в межах обмежень REST API: 2 запити на секунду для хмарного Bitrix24 (на вхідні вебхуки). Під час масових операцій (імпорт 1000 угод) кожне створення генерує подію — обробник має справлятися з піковим навантаженням.

Для коробкового Bitrix24 обмеження вищі та налаштовуються у файлі /bitrix/.settings.php. События обробляються синхронно в межах того ж PHP-процесу, що створює навантаження при частих событіях.

Вебхуки — швидкий спосіб пов'язати Bitrix24 з зовнішною системою без складної інфраструктури. Для простих сценаріїв (повідомлення у Telegram при новій угоді, синхронізація з Google Sheets) цього достатньо. Для складних інтеграцій з гарантією доставки та обробкою помилок потрібна повнофункціональна архітектура з чергою та додатком.