Вебхуки Битрикс24: входящие и исходящие - настройка и примеры

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

Что такое вебхуки в Битрикс24 и когда они нужны

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

Есть два принципиально разных направления:

• Входящий вебхук - внешний сервис отправляет запрос в Битрикс24 и что-то там создаёт или меняет: лид, сделку, комментарий, задачу.
• Исходящий вебхук - сам Битрикс24 отправляет запрос на ваш сервер при наступлении события: создали лид, изменили стадию сделки, добавили контакт.

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

Входящие вебхуки: как получить и использовать

Создаются в разделе «Разработчикам» → «Другое» → «Входящий вебхук». При создании портал просит выбрать права - здесь важно не ставить галочку «Разрешить доступ ко всем методам вне зависимости от прав», это соблазн, но заведомо избыточный. Я обычно даю доступ только к нужным разделам: CRM, задачи, календарь - смотря что нужно.

После создания вебхука вы получаете ссылку вида https://yourdomain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/, где 1 - ID пользователя, от имени которого выполняются действия, а набор символов - токен. К этой ссылке дописывается имя REST-метода.

Пример: создание лида

curl -X POST 
  "https://yourdomain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.lead.add.json" 
  -H "Content-Type: application/json" 
  -d '{
    "fields": {
      "TITLE": "Заявка с сайта",
      "NAME": "Иван",
      "PHONE": [{"VALUE": "+79991234567", "VALUE_TYPE": "WORK"}],
      "SOURCE_ID": "WEB"
    }
  }'

Этот запрос я обычно вешаю на обработчик формы - не важно, Tilda это, самописный сайт или лендинг на Next.js. Важный нюанс: у Tilda своя интеграция с Битрикс24 через маркетплейс, но она не всегда покрывает нужные поля (например, UTM-метки или кастомные поля лида), поэтому часто проще написать свой обработчик на входящем вебхуке - так у вас полный контроль над тем, что и куда падает.

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

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

Настраиваются в том же разделе «Разработчикам» → «Другое» → «Исходящий вебхук». Здесь вы указываете список событий (например, ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKADD) и URL вашего обработчика, на который Битрикс24 будет слать POST-запрос при каждом срабатывании.

Важно понимать формат: данные приходят не JSON-телом, а как обычная форма (application/x-www-form-urlencoded), с вложенной структурой вида data[FIELDS][ID]. Многие новички первый раз спотыкаются именно на этом, пытаясь распарсить тело как JSON и получая пустой объект.

Пример обработчика на Python

from flask import Flask, request

app = Flask(__name__)

@app.route("/bitrix-webhook", methods=["POST"])
def bitrix_webhook():
    data = request.form.to_dict()
    event = data.get("event")
    lead_id = data.get("data[FIELDS][ID]")

    if event == "ONCRMLEADADD":
        # дальше — запрос обратно в CRM через входящий вебхук,
        # чтобы получить остальные поля лида по ID
        pass

    return "", 200

if __name__ == "__main__":
    app.run(port=5000)

Обратите внимание: событие приходит только с ID изменившейся сущности, без остальных полей. Чтобы забрать полную карточку лида или сделки, обработчик почти всегда должен сразу же дёрнуть входящий вебхук с методом crm.lead.get или crm.deal.get - это стандартная связка «исходящий вебхук сообщил, входящий вебхук донёс данные».

Примеры интеграций на практике

Из того, что реально приходилось собирать за последний год:

• Синхронизация статусов доставки СДЭК со стадиями сделки - исходящий вебхук на смену стадии дёргает СДЭК API, а обратный статус трекинга через cron обновляет поле в карточке сделки.
• Telegram-бот на aiogram, который присылает менеджеру уведомление, если сделка простояла на одной стадии больше трёх дней - эта логика удобнее решается через периодический опрос REST-метода, а не через вебхук, так как события «истечения времени» в Битрикс24 нет.
• Связка с оплатой (по аналогии с T‑Bank на WooCommerce) - успешный платёж на сайте создаёт сделку через входящий вебхук, а изменение статуса оплаты в CRM возвращается на сайт через исходящий.
• Автоматизация в n8n - вместо самописного сервера-обработчика я всё чаще завожу вебхуки прямо на ноду Webhook в n8n, а дальше логика ветвления, фильтрации и запросов в другие сервисы собирается визуально, без отдельного бэкенда под каждую интеграцию.

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

Безопасность вебхуков Битрикс24

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

• Никогда не вызываю входящий вебхук напрямую из браузера - только с сервера, токен туда не должен попадать в публичный код.
• Держу токены в переменных окружения, а не в коде, и не коммичу .env в репозиторий.
• Выдаю вебхуку только те права, которые реально нужны для задачи - не «весь CRM», а конкретные разделы.
• Для приёма исходящих вебхуков на своём сервере дополнительно сверяю IP отправителя и обязательно использую HTTPS - иначе данные о лидах и сделках летят открытым текстом.
• Контактные данные клиентов, которые приходят через вебхуки, храню на серверах в РФ - это прямое требование 152-ФЗ по локализации персональных данных, и переносить их в зарубежные облачные таблицы для промежуточной обработки я не рекомендую.

Частые ошибки при настройке вебхуков

Из того, что регулярно вижу в чужих интеграциях (и на паре своих старых проектов тоже):

• Не проверяют HTTP-код ответа от Битрикс24 - при превышении лимита запросов портал отвечает ошибкой QUERY_LIMIT_EXCEEDED, и если это не обрабатывать с retry, часть данных просто теряется молча.
• Забывают, что исходящие вебхуки требуют публично доступного HTTPS-адреса - localhost или адрес за корпоративным файрволом не сработает, нужен либо реальный сервер, либо туннель вроде ngrok на время разработки.
• Вешают на один вебхук слишком много событий без фильтрации - сервер захлёбывается от потока уведомлений о каждом чихе в CRM, хотя реально нужно обрабатывать одно-два события.
• Не учитывают, что при массовом изменении записей (например, через импорт) события могут прилетать пачками за секунды - обработчик должен быть готов к параллельным запросам, а не рассчитан на один вызов в минуту.

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

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

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

Приложение из маркетплейса требует регистрации, прохождения модерации и работы через OAuth с обновлением токенов. Входящий вебхук - это статичная ссылка с фиксированными правами, без модерации и без протокола авторизации. Для внутренней интеграции с одним конкретным сервисом вебхука почти всегда достаточно, приложение имеет смысл делать, если планируете продавать решение другим компаниям.

Можно ли ограничить время жизни токена вебхука?

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

Что делать, если исходящий вебхук не приходит на сервер?

Первым делом проверяю логи в разделе «Вебхуки» - там видно, ушёл ли запрос и какой код ответа вернул сервер. Дальше по частоте причин: сервер вернул код, отличный от 200, адрес недоступен извне (проверял на localhost), в исключениях указано не то событие, либо сработал файрвол, который режет входящие запросы с IP-адресов Битрикс24.

Нужен ли сервер, если вебхуки принимает n8n?

Отдельный сервер под обработчик не нужен - нода Webhook в n8n сама поднимает эндпоинт и принимает POST-запросы от Битрикс24, а дальше данные разбираются и маршрутизируются внутри сценария. Это удобно, когда логика несложная: пара условий и запрос в другой сервис. Для более тяжёлой обработки (агрегация, сложная бизнес-логика, работа с очередями) я обычно всё же выношу это в отдельный код.