Вебхуки в Битрикс24: автоматизация CRM без написания приложений / Хабр

Привет, Хабр!

Частенько при создании сделки в Битрикс24 нужно отправить уведомление в тг‑канал отдела продаж, создать задачу на менеджера и записать событие во внешнюю аналитику. Три действия, которые в ручном режиме забываются через раз.

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

Для 80% задач интеграции вебхуков достаточно. Разберём, как они устроены, что с ними можно делать и где заканчиваются их возможности.

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

Входящий вебхук (Inbound Webhook) — URL для вызова REST API Битрикс24 снаружи. Вы из своего скрипта, сервера или даже из curl отправляете запрос на этот URL, и Битрикс24 выполняет действие: создаёт сделку, обновляет контакт, отправляет сообщение.

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

https://your-portal.bitrix24.ru/rest/1/abc123xyz456/

Где 1 — ID пользователя, от имени которого выполняются действия, abc123xyz456 — секретный токен. Этот URL — полноценный ключ доступа к порталу. Утечка URL = утечка доступа. Хранить его нужно как пароль: в переменных окружения, в секретах CI/CD, не в коде репозитория.

Исходящий вебхук (Outbound Webhook) — наоборот. Битрикс24 сам отправляет HTTP‑запрос на ваш URL при наступлении события: создана сделка, изменён контакт, добавлен комментарий. Вы поднимаете эндпоинт, Битрикс24 шлёт на него POST с данными события.

Создаётся там же: «Приложения — Разработчикам — Другое — Исходящий вебхук». Указываете URL обработчика, выбираете событие (например, ONCRMDEALADD — создание сделки) и токен для верификации.

Входящий вебхук: вызываем API

Формат запроса стандартный: URL вебхука + имя метода + параметры.

Создать сделку:

curl -X POST "https://portal.bitrix24.ru/rest/1/token/crm.deal.add.json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "TITLE": "Заказ с сайта #1234",
      "STAGE_ID": "NEW",
      "CURRENCY_ID": "RUB",
      "OPPORTUNITY": 150000,
      "CONTACT_ID": 42,
      "SOURCE_ID": "WEB",
      "COMMENTS": "Заказ через форму на сайте"
    }
  }'

Ответ:

{"result": 567, "time": {"duration": 0.045}}

result: 567 — ID созданной сделки. 45 мс — время выполнения. Можно использовать этот ID в следующих запросах.

Получить контакт:

curl "https://portal.bitrix24.ru/rest/1/token/crm.contact.get.json?ID=42"

Обновить сделку (сменить стадию):

curl -X POST "https://portal.bitrix24.ru/rest/1/token/crm.deal.update.json" \
  -d '{"ID": 567, "fields": {"STAGE_ID": "WON"}}'

Отправить сообщение в чат:

curl -X POST "https://portal.bitrix24.ru/rest/1/token/im.message.add.json" \
  -d '{
    "DIALOG_ID": "chat123",
    "MESSAGE": "Новая сделка: Заказ с сайта #1234, 150 000 ₽"
  }'

Методов сотни: crm.deal.*, crm.contact.*, crm.lead.*, tasks.task.*, im.message.*, disk.file.*, calendar.event.*. Полный список — в документации REST API.

Пример на Python

Форма на сайте отправляет заявку. Скрипт создаёт лид в Битрикс24 и уведомляет менеджера:

import requests
import os

WEBHOOK_URL = os.environ['BITRIX_WEBHOOK_URL']  # Из переменных окружения

def create_lead(name, phone, email, comment):
    """Создать лид в Битрикс24"""
    response = requests.post(
        f"{WEBHOOK_URL}/crm.lead.add.json",
        json={
            "fields": {
                "TITLE": f"Заявка с сайта: {name}",
                "NAME": name,
                "PHONE": [{"VALUE": phone, "VALUE_TYPE": "WORK"}],
                "EMAIL": [{"VALUE": email, "VALUE_TYPE": "WORK"}],
                "COMMENTS": comment,
                "SOURCE_ID": "WEB",
                "ASSIGNED_BY_ID": 1  # ID ответственного менеджера
            }
        }
    )
    result = response.json()
    lead_id = result.get("result")
    
    if lead_id:
        notify_manager(lead_id, name, phone)
    
    return lead_id


def notify_manager(lead_id, name, phone):
    """Уведомить менеджера в чат Б24"""
    requests.post(
        f"{WEBHOOK_URL}/im.message.add.json",
        json={
            "DIALOG_ID": 1,  # ID менеджера (личное сообщение)
            "MESSAGE": (
                f"[B]Новая заявка![/B]\n"
                f"Клиент: {name}\n"
                f"Телефон: {phone}\n"
                f"[URL=https://portal.bitrix24.ru/crm/lead/details/{lead_id}/]"
                f"Открыть лид[/URL]"
            )
        }
    )

Двадцать строк и заявка с сайта попадает в CRM с уведомлением менеджера. Без приложения, без OAuth, без маркетплейса.

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

Битрикс24 может уведомлять ваш сервер о событиях. Настраиваете URL обработчика, выбираете событие, и при каждом срабатывании Битрикс24 отправляет POST‑запрос с данными.

Пример: при создании сделки отправить данные в Google Sheets (или любую внешнюю систему).

from flask import Flask, request
import gspread

app = Flask(__name__)

@app.route('/bitrix-webhook', methods=['POST'])
def handle_deal_created():
    data = request.form  # Битрикс24 шлёт form-data, не JSON
    
    # Проверяем токен (защита от поддельных запросов)
    if data.get('auth[application_token]') != os.environ['BITRIX_EVENT_TOKEN']:
        return 'Unauthorized', 401
    
    deal_id = data.get('data[FIELDS][ID]')
    
    # Получаем полные данные сделки через входящий вебхук
    deal = requests.get(
        f"{WEBHOOK_URL}/crm.deal.get.json",
        params={"ID": deal_id}
    ).json()['result']
    
    # Пишем в Google Sheets
    sheet = gspread.service_account().open("Сделки").sheet1
    sheet.append_row([
        deal['ID'],
        deal['TITLE'],
        deal['OPPORTUNITY'],
        deal['DATE_CREATE']
    ])
    
    return 'OK', 200

Исходящий вебхук присылает только ID сущности, не полные данные. Чтобы получить детали, нужно сделать обратный запрос через входящий вебхук. Это два вебхука, работающих в связке.

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

Если нужно выполнить несколько операций за раз (создать сделку + добавить товары + назначить задачу), отдельные запросы неэффективны. Метод batch объединяет до 50 вызовов в один HTTP‑запрос:

response = requests.post(
    f"{WEBHOOK_URL}/batch.json",
    json={
        "halt": 0,  # 0 = продолжать при ошибке, 1 = остановиться
        "cmd": {
            "deal": "crm.deal.add?fields[TITLE]=Тест&fields[OPPORTUNITY]=50000",
            "task": "tasks.task.add?fields[TITLE]=Обработать сделку&fields[RESPONSIBLE_ID]=1",
            "notify": "im.message.add?DIALOG_ID=chat5&MESSAGE=Новая сделка создана"
        }
    }
)

results = response.json()['result']
# results['result']['deal'] — ID сделки
# results['result']['task'] — ID задачи

Кроме экономии HTTP‑запросов, batch позволяет использовать результат одной команды в другой через $result:

"cmd": {
    "deal": "crm.deal.add?fields[TITLE]=Тест",
    "task": "tasks.task.add?fields[TITLE]=Обработать сделку $result[deal]&fields[RESPONSIBLE_ID]=1"
}

Задача будет содержать ID только что созданной сделки в заголовке.

Лимиты и блокировки

Облачный Битрикс24 ограничивает количество REST‑запросов. Базовый лимит — 2 запроса в секунду на один вебхук. При превышении получим HTTP 429 (Too Many Requests). При систематическом превышении — блокировка вебхука с уведомлением администратору.

Документация описывает причины блокировок: слишком много запросов, тяжёлые операции (массовый импорт), некорректные сценарии (опрос CRM каждые 5 секунд).

Рекомендации по работе с лимитами:

Используйте batch — 50 операций за один запрос вместо 50 отдельных. Это 1 запрос вместо 50, при том же результате.
Вместо «каждые 10 секунд проверяем, есть ли новые сделки» — настройте исходящий вебхук на событие ONCRMDEALADD. Битрикс24 сам сообщит, когда появится новая сделка.
Для массовых операций (импорт 10 000 контактов) — добавьте задержку между batch‑запросами: 500 мс — 1 секунда. Или используйте метод crm.contact.list с постраничной навигацией вместо запроса каждого контакта по ID.
Мониторьте нагрузку в разделе «Приложения — Разработчикам — Статистика». Там видно количество запросов по каждому вебхуку и приложению с разбивкой по дням.

Вебхуки в бизнес‑процессах

Менее известная возможность: вебхуки можно вызывать из визуального дизайнера бизнес‑процессов Битрикс24. Активити «Вебхук» отправляет HTTP‑запрос на внешний URL прямо из бизнес‑процесса, без написания кода.

Сценарий: при переходе сделки в стадию «Согласование договора» бизнес‑процесс вызывает внешний сервис, который генерирует PDF‑договор по шаблону и возвращает ссылку. Ссылка сохраняется в поле сделки. Менеджер видит готовый договор без ручной работы.

Для более сложных сценариев есть приложения‑конструкторы вроде Рест Действия и RoboREST, которые позволяют создавать кастомных роботов для бизнес‑процессов, обращающихся к REST API — в режиме no‑code или через Python‑скрипты.

Безопасность

Вебхук — это ключ к порталу. Утечка URL означает, что кто угодно может читать и модифицировать данные CRM.

Несколько правил:

Не храните URL вебхука в коде. Переменные окружения, секреты CI/CD, хранилище секретов (Vault, AWS Secrets Manager). Не в .env файле, закоммиченном в Git.
Ограничивайте права. При создании вебхука выбирайте минимально необходимые права. Если скрипт только создаёт сделки — не давайте доступ к задачам, диску и чатам. Принцип наименьших привилегий.
Один вебхук — одна интеграция. Не используйте один URL для сайта, телеграм‑бота и CRM‑аналитики. Если одна интеграция скомпрометирована — заменяете один вебхук, а не перенастраиваете всё.
Для исходящих вебхуков — проверяйте токен. Битрикс24 отправляет auth[application_token] в каждом запросе. Сравните его с ожидаемым значением, прежде чем обрабатывать данные.

Вебхуков часто недостаточно

Вебхуки — инструмент для конкретных, точечных интеграций. Они не подходят, когда нужно полноценное приложение с интерфейсом внутри Битрикс24 (виджеты в карточке сделки, кастомные вкладки). Для этого нужно полноценное приложение с OAuth‑авторизацией и регистрацией.

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

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

Несмотря на ограничения, для подавляющего большинства задач интеграции вебхуки закрывают потребность полностью. Один URL и немного кода.

Если вам важно не просто знать возможности Битрикс24, а уметь выстраивать в нём рабочие процессы, автоматизировать CRM и собирать интеграции под реальные задачи бизнеса, обратите внимание на курс «Интегратор Битрикс24».

С 1 по 4 апреля в OTUS действует дополнительная скидка 10% по промокоду birthday на любые курсы. Она суммируется с другими скидками, поэтому тем, кто давно планировал обучение, сейчас можно выбрать более комфортные условия.
☛ [Узнать о скидке 10% ]

А чтобы сначала разобраться в одном из ключевых инструментов автоматизации, приходите на открытый урок:

«Бизнес‑процессы CRM. Стандартные активити» 22 апреля в 20:00.
☛ [Начать с открытого урока]

Вебхуки в Битрикс24: автоматизация CRM без написания приложений