REST API Битрикс24: входящие и исходящие вебхуки на примерах

REST API — основной способ связать Битрикс24 с сайтом, 1С, складом, ботами и любыми внешними сервисами. Для внутренних интеграций проще всего использовать вебхуки: не нужно регистрировать приложение и возиться с OAuth.

Входящий вебхук

В разделе «Разработчикам» (или «Приложения → Вебхуки») создайте входящий вебхук и выберите права, например CRM. Вы получите адрес вида:

https://company.bitrix24.ru/rest/1/abcd1234secret/

Это и логин, и пароль одновременно. Храните его на сервере в переменных окружения, никогда в клиентском JavaScript.

Пример: заявка с сайта в CRM

$webhook = getenv('B24_WEBHOOK');
$payload = [
    'fields' => [
        'TITLE' => 'Заявка с сайта',
        'NAME' => $name,
        'PHONE' => [['VALUE' => $phone, 'VALUE_TYPE' => 'WORK']],
        'SOURCE_ID' => 'WEB',
        'UTM_SOURCE' => $_COOKIE['utm_source'] ?? '',
    ],
    'params' => ['REGISTER_SONET_EVENT' => 'Y'],
];
$ch = curl_init($webhook . 'crm.lead.add.json');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
$result = json_decode(curl_exec($ch), true);

Если CRM работает без лидов, используйте crm.deal.add и предварительно найдите или создайте контакт через crm.contact.list и crm.contact.add, чтобы не плодить дубли.

Исходящий вебхук

Исходящий вебхук отправляет POST-запрос на ваш сервер при событии: ONCRMDEALUPDATE, ONCRMLEADADD и другие. В запросе приходит ID сущности и токен приложения — проверяйте токен, прежде чем что-то делать. Затем получите актуальные данные через API (crm.deal.get): в самом событии их нет.

Пакетные запросы

Метод batch выполняет до 50 команд за один HTTP-запрос. Это главный способ уложиться в лимиты при массовых операциях: выгрузке сделок, синхронизации каталога.

Надёжность интеграции

• Очередь. Заявку с сайта сначала сохраните у себя, затем отправьте в Битрикс24. Если API недоступен, заявка не потеряется.
• Повторы с паузой при ошибках лимитов и сетевых сбоях.
• Идемпотентность: храните соответствие ваших ID и ID в Битрикс24, чтобы повтор не создал дубль.
• Логи запросов и ответов — без них разбор инцидентов превращается в гадание.

Вебхук или приложение

	Вебхук	Приложение
Для чего	Интеграция одного портала	Тиражируемое решение, маркетплейс
Авторизация	Секретный адрес	OAuth 2.0
Встройка в интерфейс	Нет	Да (вкладки, виджеты)

Интеграции — обычная часть внедрения Битрикс24. Если нужно подружить CRM с сайтом, 1С или своим сервисом — обсудим.