Как создать вебхук в Битрикс24: настройка обмена с сайтом

Вебхук в Битрикс24 - это URL, через который сайт и портал обмениваются данными без написания отдельного REST-приложения с регистрацией в маркетплейсе. Я настраивал такую связку десятки раз: заявка с Tilda падает лидом в CRM, смена статуса сделки уходит уведомлением в aiogram-бота менеджера, а трек-номер СДЭК возвращается в карточку заказа. Ниже разбираю, как создать вебхук в Битрикс24 для обоих направлений обмена и что учесть, чтобы данные не терялись и не утекали посторонним.

Входящий и исходящий вебхук в Битрикс24: в чём разница

В Битрикс24 два типа вебхуков, и путать их не стоит, потому что настраиваются они в разных местах и решают разные задачи.

Входящий вебхук принимает запросы от внешних систем. Вы создаёте его в портале, получаете уникальный URL и дальше с этим URL можно дергать методы REST API: добавлять лиды, обновлять сделки, менять стадии воронки. Именно через входящий вебхук Tilda или WooCommerce отправляют данные заявки в CRM.

Исходящий вебхук работает в обратную сторону. Портал сам отправляет POST-запрос на указанный вами URL при наступлении события: создали сделку, изменили статус, добавили комментарий. На эти запросы отвечает уже ваш сервер или обработчик в n8n.

На практике в одной интеграции обычно нужны оба: входящий, чтобы отдавать заявки в CRM, и исходящий, чтобы получать обратно статусы и события.

Как создать входящий вебхук в Битрикс24 пошагово

Входящий вебхук создаётся из раздела «Разработчикам». Заходите в левое меню портала, открываете «Ещё» или «Разработчикам» (пункт называется по-разному в зависимости от тарифа и версии интерфейса), там выбираете «Другое» и дальше «Входящий вебхук».

Далее порядок такой:

• Указываете название вебхука, чтобы через полгода не гадать, для чего он создан. Пишу конкретно: «Tilda - лиды с формы заказа» или «WooCommerce - синхронизация заказов».
• Отмечаете права доступа. Для приёма лидов достаточно scope crm. Если планируете ставить задачи из внешней системы, добавляете task, для работы с телефонией - telephony. Лишние права не даю никогда: чем шире доступ у вебхука, тем больнее его утечка.
• Сохраняете и получаете URL вида https://ваш-портал.bitrix24.ru/rest/1/хххххххххххххххх/. Число после rest/ - это ID пользователя, от имени которого выполняются методы, а буквенный набор - секретный токен.

Этот URL и есть рабочий адрес для вызова методов REST API. Например, чтобы добавить лид методом crm.item.add, где entityTypeId 1 означает лид (прежний crm.lead.add в документации помечен DEPRECATED, хотя пока доступен):

curl -X POST https://ваш-портал.bitrix24.ru/rest/1/хххххххххххххххх/crm.item.add.json 
  -H "Content-Type: application/json" 
  -d '{"entityTypeId": 1, "fields": {"title": "Заявка с Tilda", "name": "Иван", "fm": [{"typeId": "PHONE", "valueType": "WORK", "value": "+79991234567"}]}}'

Важный момент: пользователь, от имени которого создан вебхук, должен иметь права на добавление лидов и в самой CRM, а не только права на сам вебхук. Если создаёте вебхук от имени сотрудника с урезанной ролью, часть методов будет возвращать ошибку доступа, даже если scope выставлен верно.

Исходящий вебхук: подписка на события портала

Исходящий вебхук настраивается там же, в разделе «Разработчикам» - «Другое» - «Исходящий вебхук». Здесь логика обратная: вы указываете не URL Битрикс24, а URL своего обработчика, куда портал будет слать данные.

При создании выбираете конкретное событие из списка: ONCRMDEALADD для новой сделки, ONCRMDEALUPDATE для изменения, ONCRMLEADADD для нового лида и так далее. На один обработчик можно повесить несколько событий, если логика на стороне сервера умеет их различать по полю event в теле запроса.

Портал отправляет POST-запрос с полями event, data (с ID изменённого объекта, но без всех его полей - это специально сделано для экономии трафика) и auth с токеном приложения. Чтобы получить остальные данные сделки, обработчик сам дергает метод crm.deal.get через входящий вебхук или REST-приложение.

Здесь и разница с событиями через REST-приложение: у исходящего вебхука нет OAuth, авторизация проще, но и живёт он только пока действителен URL и токен приложения. Если сайт переехал на новый домен, вебхук нужно пересоздавать вручную.

Обработчик вебхука на сайте: пример на PHP

Сервер, который принимает исходящий вебхук, обязан быстро ответить 200 OK и только потом заниматься обработкой, иначе Битрикс24 посчитает вызов неуспешным и будет повторять его по своему расписанию ретраев.

<?php
$raw = file_get_contents('php://input');
parse_str($raw, $data);

if (empty($data['auth']['application_token']) ||
    $data['auth']['application_token'] !== getenv('BITRIX_APP_TOKEN')) {
    http_response_code(403);
    exit;
}

http_response_code(200);

$event = $data['event'] ?? '';
$dealId = $data['data']['FIELDS']['ID'] ?? null;

if ($event === 'ONCRMDEALUPDATE' && $dealId) {
    // ставим задачу в очередь и выходим, тяжёлую логику сюда не пишем
    file_put_contents('/var/queue/deal_' . $dealId . '.json', $raw, FILE_APPEND);
}

Проверка application_token обязательна: без неё любой, кто узнает URL обработчика, сможет слать фиктивные события и подделывать данные о сделках. Токен приложения выдаётся при создании исходящего вебхука и не совпадает с токеном входящего.

Примеры на практике: Tilda, WooCommerce, СДЭК и n8n

Чаще всего вебхуки Битрикс24 всплывают в одной из четырёх связок.

Tilda отправляет данные формы через встроенный webhook-интеграцию или через кастомный скрипт на странице, который дергает crm.item.add напрямую с фронта (так делать не советую - токен вебхука виден в коде страницы) либо через промежуточный обработчик на своём сервере, который прячет токен и уже от своего имени идёт в Битрикс24.

WooCommerce при оформлении заказа через хук woocommerce_order_status_changed отправляет POST на входящий вебхук Битрикс24, создавая сделку и привязывая к ней товарные позиции через crm.item.productrow.set (прежний crm.deal.productrows.set в документации помечен DEPRECATED, хотя пока доступен).

СДЭК работает в обе стороны: на входе трек-номер записывается в сделку после оформления доставки, на выходе исходящий вебхук ловит смену статуса сделки на «Готов к отгрузке» и запускает вызов API СДЭК для создания заказа на доставку.

n8n я обычно ставлю между сайтом и Битрикс24, когда логика обмена не сводится к одному вызову. Нода HTTP Request дергает URL входящего вебхука напрямую, без строки кода, а нода Webhook в n8n принимает исходящие события от портала и дальше маршрутизирует их: часть в Telegram-бота на aiogram, часть в Google Таблицы для отчётов, часть обратно в CRM с обогащёнными данными. Для несложных сценариев это быстрее, чем поднимать отдельный сервер под обработчик.

Если обмен разрастается до пары десятков сценариев и условий, я обычно выношу его в отдельный слой кастомных интеграций между сайтом и CRM, а не пытаюсь удержать всё в одной цепочке вебхуков - так проще потом менять логику без риска сломать рабочий поток заявок.

Безопасность вебхука: токен, HTTPS, IP-ограничения

Вебхук, особенно входящий, по сути равносилен паролю от части CRM. Несколько правил, которые соблюдаю на каждом проекте:

• Никогда не кладу URL входящего вебхука в код на фронте. Заявка с формы всегда идёт через свой сервер-посредник, а токен хранится в переменных окружения, не в репозитории.
• Ограничиваю scope вебхука минимально нужными правами. Для приёма лидов не даю доступ к телефонии или задачам, даже если «вдруг пригодится».
• Для обработчика исходящего вебхука проверяю application_token на каждый запрос, а не только при первой настройке.
• Держу обработчик только на HTTPS. Без сертификата Битрикс24 либо откажется слать события, либо данные заявок и телефонов клиентов пойдут открытым текстом.
• Периодически проверяю список вебхуков в разделе «Разработчикам» и удаляю те, что остались от старых интеграций - забытый вебхук с правами на CRM это открытая дверь.

Отдельно про хранение данных клиентов, которые приходят через вебхук: держу их на серверах в РФ, а не в сторонних облачных таблицах - это требование 152-ФЗ по локализации персональных данных, и на практике проще сразу писать в базу на своём хостинге, чем потом переносить.

Частые вопросы

Сколько вебхуков можно создать в одном портале Битрикс24?

Ограничения по количеству вебхуков как такового нет, портал позволяет создавать отдельный вебхук под каждую интеграцию. На практике я завожу по одному входящему вебхуку на каждый источник заявок (Tilda, WooCommerce, форма на лендинге), чтобы при утечке или ошибке можно было отключить только один канал, не трогая остальные.

Работают ли вебхуки на бесплатном тарифе Битрикс24?

Да, входящие и исходящие вебхуки доступны на бесплатном тарифе. Ограничения бесплатного тарифа касаются числа пользователей и объёма хранилища CRM, а не работы REST API через вебхуки.

Как проверить, что вебхук в Битрикс24 работает?

Для входящего вебхука проще всего вызвать любой безопасный метод через браузер или curl, например crm.lead.fields, и посмотреть, вернётся ли JSON с полями вместо ошибки авторизации. Для исходящего вебхука в разделе «Разработчикам» - «Другое» есть история вызовов с кодами ответа вашего сервера, там видно, доходят ли события и с каким статусом отвечает обработчик.

Чем вебхук отличается от REST API-приложения в Битрикс24?

Вебхук проще: не нужна регистрация в маркетплейсе, модерация и OAuth-авторизация, вы получаете готовый URL за пару кликов. REST-приложение сложнее в настройке, зато даёт доступ к событиям через более гибкую систему прав, обновление токена по OAuth и возможность публикации в каталоге для других порталов. Для связки одного сайта с одним порталом вебхука обычно достаточно.