Битрикс24 REST API: Получать уведомления о новых лидах

Сценарий из mcp-everything. Актуально на 2026-10-24.

Реагировать на появление лида в Битрикс24 сразу: отправить приветственное письмо, записать в свою базу.

Подписка на события работает только в приложении (OAuth), не во входящем вебхуке — вебхук вернёт WRONG_AUTH_TYPE. Создай локальное приложение на портале.
Зарегистрируй обработчик: event.bind с event = ONCRMLEADADD и handler — адрес твоего сервера (с доменом, localhost не принимается).
Битрикс24 пришлёт POST-запрос с data[FIELDS][ID] — id нового лида. Проверь application_token из запроса, чтобы отсечь чужие вызовы.
Получи сам лид: crm.item.get с entityTypeId = 1 и этим id.
access_token приложения живёт час — обновляй его через https://oauth.bitrix.info/oauth/token/ по refresh_token.

# Вызов от имени приложения: токен передаётся в параметре auth
curl -X POST "https://<портал>.bitrix24.ru/rest/event.bind.json" \
  -H 'Content-Type: application/json' \
  -d '{"auth": "<access_token>", "event": "ONCRMLEADADD", "handler": "https://example.ru/b24/lead-added"}'

curl -X POST "https://<портал>.bitrix24.ru/rest/crm.item.get.json" \
  -H 'Content-Type: application/json' \
  -d '{"auth": "<access_token>", "entityTypeId": 1, "id": 253}'

Базовые URL

Боевой (входящий вебхук): https://<ваш-портал>.bitrix24.ru/rest/<id пользователя>/<код вебхука>/<метод>.json
Боевой (приложение OAuth 2.0): https://<ваш-портал>.bitrix24.ru/rest/<метод>.json
Сервер авторизации OAuth: https://oauth.bitrix.info/

Авторизация

Тип: Другое

Два способа:

Входящий вебхук — постоянный секретный код в URL запроса вместе с ID пользователя, создавшего вебхук. Метод выполняется с правами этого пользователя и в рамках выбранных в настройках вебхука скоупов. Подходит для интеграции с одним порталом. Код вебхука — это пароль: не публикуйте его и не передавайте в браузерный код.
OAuth 2.0 — для локальных и тиражных приложений. Временный access_token передаётся в параметре auth; живёт один час и обновляется через https://oauth.bitrix.info/oauth/token/ с помощью refresh_token. client_secret используется только в запросах к oauth.bitrix.info.

Без данных авторизации запрос отклоняется с ошибкой NO_AUTH_FOUND.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
	"entityTypeId": 2,
	"fields": {
		"title": "New Deal",
		"typeId": "SALE",
		"stageId": "NEW"
	}
}' \
https://your-domain.bitrix24.com/rest/1/8g9l071eismy9q2l/crm.item.add.json

Методы сценария

crm.item.get — Получить элемент по ID

Параметр	Где	Тип	Обяз.	Описание
`entityTypeId`	body	integer	да	Тип объекта CRM
`id`	body	integer	да	ID элемента
`useOriginalUfNames`	body	boolean	нет	Формат имён пользовательских полей

event.bind — Подписаться на событие

Регистрирует обработчик события (например ONCRMLEADADD). Работает только в контексте приложения: через вебхук вернёт WRONG_AUTH_TYPE. Bitrix24 отправляет данные события POST-запросом на адрес обработчика.

Параметр	Где	Тип	Обяз.	Описание
`event`	body	string	да	Код события, например ONCRMLEADADD
`handler`	body	string	да	URL обработчика; хост должен содержать точку, localhost не принимается
`auth_type`	body	integer	нет	Пользователь, под которым авторизуется обработчик
`event_type`	body	string	нет	online (по умолчанию) или offline
`auth_connector`	body	string	нет	Ключ источника для офлайн-событий
`options`	body	object	нет	Доп. настройки события

Нюансы

Методы crm.deal.*, crm.lead.* и аналогичные больше не развиваются; для новых интеграций используйте crm.item.*.
Ошибку распознают по полям ответа, а не по HTTP-статусу: подзапросы batch с ошибкой приходят со статусом 200, а поле error может быть пустым — тогда причина только в error_description.
В ответе batch поле result.result_error есть всегда; признак ошибки — непустое содержимое.
Методы *.list отдают по 50 записей; для больших выгрузок используйте пагинацию без подсчёта общего количества и batch.
Некоторые методы (например placement.bind, event.bind) недоступны вебхуку и возвращают WRONG_AUTH_TYPE.
Несколько приложений с одного сервера к одному порталу делят общий лимит частоты запросов — лимит учитывает IP-адрес источника.
Запрос по http вместо https вернёт INVALID_REQUEST.
У Битрикс24 есть MCP-сервер b24-dev-mcp для AI-инструментов: он даёт доступ к официальной документации REST API (без доступа к данным портала).

Другие сценарии

Если этого недостаточно — официальная документация: https://apidocs.bitrix24.ru/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/bitrix24.md