Исходящий вебхук Битрикс24: что приходит в запросе и как проверить токен
Исходящий вебхук Битрикс24 шлёт форму, а не JSON, и только ID объекта. Проверка application_token, crm.item.get, лимиты REST и таблица ошибок.
Опубликовано Обновлено 18 минут чтения
- битрикс24
- вебхуки
- crm
- исходящий вебхук
- rest api
Исходящий вебхук Битрикс24 отправляет POST с телом application/x-www-form-urlencoded, а не JSON. В теле код события event, номер обработчика event_handler_id, ID объекта в data[FIELDS][ID], время ts и блок auth с application_token. Полей самой сделки в запросе нет. Подлинность проверяется одним сравнением: auth[application_token] должен совпасть с токеном из настроек вебхука. Данные сделки запрашиваются отдельно, методом crm.item.get через входящий вебхук.
На схеме — вся цепочка, ниже — каждое звено: формат запроса, поведение при сбоях, обработчики на PHP, Python и Node.js, чтение сделки с учётом лимитов REST и таблица «симптом → причина».
Что присылает исходящий вебхук Битрикс24
Пример из документации Битрикс24 для события ONCRMDEALADD. Документация показывает его в виде JSON, но по сети уходит форма, и все значения в ней — строки:
event=ONCRMDEALADD event_handler_id=975 data[FIELDS][ID]=7405 ts=1766047124 auth[domain]=some-domain.bitrix24.ru auth[client_endpoint]=https://some-domain.bitrix24.ru/rest/ auth[server_endpoint]=https://oauth.bitrix24.tech/rest/ auth[member_id]=d897063e1ce7c5eb9f04b9751eef5915 auth[application_token]=jvh9y1ulvt2m6k5or90v9mg8nn32ozas
Здесь пары разнесены по строкам и не закодированы. В теле они соединены через &, а скобки в ключах по правилам формы кодируются: data%5BFIELDS%5D%5BID%5D=7405.
| Поле | Что в нём |
|---|---|
event | код события в верхнем регистре, например ONCRMDEALADD |
event_handler_id | ID подписки; через REST его не узнать, но он удобен как метка в логах |
data[FIELDS][ID] | ID сделки, лида или другого объекта CRM — строкой |
ts | Unix-время в секундах |
auth[domain] | адрес портала |
auth[member_id] | идентификатор портала |
auth[application_token] | токен, по которому видно, что запрос прислал ваш портал |
В auth исходящего вебхука приходят только domain, client_endpoint, server_endpoint, member_id и application_token. Токенов OAuth (access_token, refresh_token) нет. Примеры на страницах событий в документации показаны для приложений, и там эти токены есть. Не пишите по ним код для вебхука.
Самые частые события CRM:
| Событие | Когда срабатывает |
|---|---|
ONCRMDEALADD | создана сделка |
ONCRMDEALUPDATE | сделка изменена |
ONCRMDEALDELETE | сделка удалена |
ONCRMLEADADD | создан лид |
ONCRMLEADUPDATE | лид изменён |
ONCRMCONTACTADD | создан контакт |
ONCRMDEALUPDATE сообщает только факт изменения. Какое поле поменялось, из события не узнать: нужно прочитать сделку и сравнить с тем, что сохранено у вас.
Как Битрикс24 доставляет события
От этих свойств зависит, как писать обработчик. Всё ниже взято из документации Битрикс24.
- Через очередь. Портал не вызывает обработчик сам: событие попадает на сервер очередей, и POST уходит оттуда. Поэтому запрос может прийти с небольшой задержкой.
- Без повторов. Если обработчик не ответил или вернул ошибку, сбой фиксируется, но событие повторно не отправляется. Упал сервер на пять минут — события за эти пять минут потеряны.
- Медленный ответ — реже события. Если обработчик отвечает медленно, сервер очередей увеличивает интервалы между запросами.
- Без регулировки нагрузки. Если в портале разом изменили тысячу сделок, обработчик получит тысячу вызовов подряд.
Из этого следует главное правило: обработчик проверяет токен, ставит задачу в свою очередь и сразу отвечает 200. Запросы в REST, запись в базу, отправку писем делает фоновая задача.
Чего в документации о событиях и вебхуках нет: сохраняется ли порядок событий и может ли одно событие прийти дважды. Значение ts описано по-разному: в обзоре событий — как время возникновения, на страницах событий — как время отправки из очереди. Поэтому не стройте логику на порядке запросов и на ts. Надёжная схема — идемпотентная: по ID из события перечитать сделку целиком и записать её текущее состояние. Два одинаковых события дадут одну и ту же запись, а событие «из прошлого» не затрёт свежие данные. Для сравнения версий в ответе crm.item.get есть updatedTime.
Ещё одна неясность — цикл. Документация не уточняет, вызывает ли изменение сделки через REST новое ONCRMDEALUPDATE. Если обработчик сам меняет сделку в ответ на это событие, записывайте значение только тогда, когда оно действительно отличается. Тогда цикл, если он есть, оборвётся на втором шаге.
Исходящий и входящий вебхук: два разных секрета
Исходящий вебхук срабатывает на событие: портал сам отправляет POST на ваш URL. Входящий работает в обратную сторону. Это секретный адрес вида https://ваш-портал.bitrix24.ru/rest/1/секретный_код/метод, через который ваш код вызывает REST API с правами сотрудника, создавшего вебхук. Полноценной интеграции нужны оба: исходящий сообщает об изменении, входящий даёт прочитать данные.
Секреты у них разные и не взаимозаменяемы. «Токен приложения» исходящего вебхука нужен только для проверки запросов от портала. Код в адресе входящего вебхука даёт доступ к данным CRM, его хранят как пароль.
Как создать исходящий вебхук
По документации Битрикс24:
- Откройте раздел «Приложения» → «Разработчикам».
- Перейдите на вкладку «Готовые сценарии» → «Другое» → «Исходящий вебхук».
- Укажите URL обработчика.
- Выберите одно или несколько событий, например
ONCRMDEALADD. - Нажмите «Создать». В форме появится поле «Токен приложения» — сохраните его значение.
- Проверьте вызов: создайте или измените сделку.
Ограничения:
- URL должен быть доступен из интернета и принимать POST.
localhost, адреса локальной сети и HTTPS с самоподписанным сертификатом не подойдут. - Берите HTTPS: по HTTP токен и данные события идут открытым текстом.
- В деморежиме исходящий вебхук недоступен. В коробочной версии нужна активная лицензия.
- Если обработчик стоит за фаерволом, разрешите входящие запросы с серверов очередей Битрикс24. Их адреса меняются, актуальный список отдаёт
https://repos.1c-bitrix.ru/webhook/app.json. Документация советует опрашивать его раз в 5–10 минут и не чаще раза в минуту. - Прокси или WAF перед обработчиком не должны отбрасывать запросы с типом
application/x-www-form-urlencoded. - Коробочному Битрикс24 нужен исходящий доступ по HTTPS к
oauth.bitrix24.tech: события уходят в очередь через него. Исключение — коробка со своим провайдером авторизации: тогда события идут прямо с её сервера.
Как увидеть запрос до того, как писать код
Чтобы посмотреть, что присылает портал, поставьте в вебхук адрес hook.csap.ru:
- Откройте hook.csap.ru и нажмите «Открыть мой адрес». Регистрация не нужна.
- Скопируйте адрес вида
https://hook.csap.ru/t/ВАШ_ТОКЕНи допишите путь, например/b24. - Вставьте адрес в поле URL исходящего вебхука. Начинайте с
https://: наhttp://сервис отвечает перенаправлением 301. - Создайте сделку.
Ниже — запрос из примера документации, отправленный на адрес сервиса. Снимки сделаны на тестовом стенде сервиса, а не на настоящем портале. Форма разобрана в дерево: ключ data[FIELDS][ID] стал веткой data → FIELDS → ID.
Кнопка «Путь» на строке дерева копирует ключ в исходном виде, data[FIELDS][ID]. Переключатель «Как есть» показывает тело таким, каким оно пришло, с закодированными скобками:
На бесплатном тарифе события могут потеряться. Бесплатный тариф hook.csap.ru принимает до 5 запросов в секунду на аккаунт, по всем адресам, и 500 в месяц; сверх этого адрес отвечает
429. Битрикс24 не повторяет, поэтому при массовом изменении сделок часть событий до обработчика не дойдёт, а живой портал может выбрать месячные 500 запросов за несколько дней — дальше события теряются до конца месяца. Отлаживайте на одной-двух сделках, без массовых изменений; для потока событий — платный тариф (на «Индивидуальном» 10 запросов в секунду и 20 000 в месяц, тарифы) или свой сервер.
Обработчик: проверка application_token
Тело — форма. Если читать его как JSON, json_decode(file_get_contents('php://input')) в PHP вернёт null, а в Express 5 и без парсера, и с express.json() req.body будет undefined.
Три обработчика ниже ведут себя одинаково. Верный токен — 200. Чужой токен, запрос без токена, JSON вместо формы и токен, переданный массивом (auth[application_token][]=…), — 403. Документация Битрикс24 советует при несовпадении отвечать именно 403. Токен сравнивается за постоянное время: обычное сравнение строк (==, ===) останавливается на первом несовпадающем символе, и по скорости ответа токен можно подбирать по одному символу. Если переменная B24_APP_TOKEN не задана, Python и Node.js не запускаются, а PHP отвечает 500. Это не перестраховка. Без такой проверки пустой токен во Flask пропускает любой запрос без токена: compare_digest("", "") возвращает True. А незаданная переменная в Node.js после String() превращается в строку "undefined", и её можно просто прислать.
PHP
PHP сам разбирает скобки в ключах формы: $_POST['data']['FIELDS']['ID'] доступно сразу.
<?php // Обработчик исходящего вебхука Битрикс24. // B24_APP_TOKEN — значение поля «Токен приложения» из настроек вебхука. $appToken = (string) getenv('B24_APP_TOKEN'); if ($appToken === '') { // Без токена проверять нечем. 500, а не 403: виновата настройка сервера. error_log('b24: B24_APP_TOKEN is not set'); http_response_code(500); exit; } // Тело — форма. PHP сам разбирает скобки в ключах во вложенные массивы. $got = $_POST['auth']['application_token'] ?? ''; // is_string: auth[application_token][]=… превратится в массив, а не в строку. if (!is_string($got) || !hash_equals($appToken, $got)) { http_response_code(403); exit; } $event = (string) ($_POST['event'] ?? ''); $id = (int) ($_POST['data']['FIELDS']['ID'] ?? 0); // все значения приходят строками // В лог — событие и ID, но не токен. error_log("b24: $event $id"); // Здесь только постановка задачи в очередь: медленный ответ Битрикс24 // замечает и начинает присылать события реже. // queuePush($event, $id); http_response_code(200);
Python (Flask)
Во Flask ключи формы плоские: скобки остаются частью имени.
import hmac import logging import os from flask import Flask, request APP_TOKEN = os.environ.get("B24_APP_TOKEN", "") # «Токен приложения» из настроек вебхука if not APP_TOKEN: # С пустым токеном compare_digest("", "") вернёт True для любого запроса без токена. raise SystemExit("B24_APP_TOKEN is not set") logging.basicConfig(level=logging.INFO) log = logging.getLogger("b24") app = Flask(__name__) @app.post("/b24") def bitrix24_webhook(): # Ключи формы во Flask плоские: скобки остаются частью имени. got = request.form.get("auth[application_token]", "") if not hmac.compare_digest(got.encode(), APP_TOKEN.encode()): return "", 403 event = request.form.get("event", "") item_id = request.form.get("data[FIELDS][ID]", "") log.info("b24: %s %s", event, item_id) # без токена # queue_push(event, item_id) — тяжёлую работу в фон, ответ сразу return "", 200 if __name__ == "__main__": app.run(port=3000)
Node.js (Express)
В Express 5 у express.urlencoded() по умолчанию extended: false. Без extended: true объекта req.body.auth не будет: токен окажется в плоском ключе req.body["auth[application_token]"].
import crypto from "node:crypto"; import express from "express"; const APP_TOKEN = process.env.B24_APP_TOKEN ?? ""; // «Токен приложения» из настроек вебхука if (!APP_TOKEN) { // Без этой проверки String(undefined) превратится в токен "undefined". throw new Error("B24_APP_TOKEN is not set"); } const app = express(); // extended: true — ключи со скобками разбираются во вложенные объекты. app.use(express.urlencoded({ extended: true })); // sameToken — сравнение за постоянное время; не строка (например, массив) — отказ. function sameToken(got) { if (typeof got !== "string") return false; const a = Buffer.from(got); const b = Buffer.from(APP_TOKEN); return a.length === b.length && crypto.timingSafeEqual(a, b); } app.post("/b24", (req, res) => { if (!sameToken(req.body?.auth?.application_token)) { return res.sendStatus(403); } const event = String(req.body.event ?? ""); const id = Number(req.body.data?.FIELDS?.ID); // все значения приходят строками console.log("b24:", event, id); // без токена // queuePush(event, id) — тяжёлую работу в фон, ответ сразу res.sendStatus(200); }); app.listen(3000);
Что ответили обработчики на одни и те же запросы (PHP 7.4, Python 3.12 с Flask 3.1, Node.js 24 с Express 5):
| Запрос | PHP | Flask | Express |
|---|---|---|---|
| форма из документации, верный токен | 200 | 200 | 200 |
| чужой токен | 403 | 403 | 403 |
без auth[application_token] | 403 | 403 | 403 |
| JSON вместо формы | 403 | 403 | 403 |
токен массивом auth[application_token][] | 403 | 403 | 403 |
B24_APP_TOKEN не задан | 500 | не запускается | не запускается |
Если один обработчик принимает события от нескольких порталов, документация советует хранить токен вместе с auth[member_id] и искать сохранённый токен по нему. Сам токен — секрет: в логи и сообщения об ошибках он попадать не должен.
Отладка на своём компьютере
Портал не отправит запрос на localhost. Укажите в вебхуке адрес hook.csap.ru и включите туннель: запрос на …/t/ВАШ_ТОКЕН/b24 уйдёт на http://localhost:3000/b24, а ответ обработчика получит Битрикс24. Для туннеля нужен вход в аккаунт, на бесплатном тарифе доступна одна сессия.
curl -fsSL https://hook.csap.ru/cli/install.sh | WEBHOOKS_BASE_URL=https://hook.csap.ru sh webhooks login --web --server https://hook.csap.ru webhooks tunnel --endpoint ВАШ_ТОКЕН --target http://localhost:3000
Пришедший запрос можно отправить на обработчик ещё раз: webhooks replay 42 --target http://localhost:3000, где 42 — номер запроса в ленте. Так не нужно создавать новую сделку после каждой правки кода.
Проверку токена можно включить и на самом адресе, ещё до того, как написан обработчик. На странице ленты: «Правила» → блок «Проверка подписи» → провайдер «Битрикс24» → в поле «Секрет» токен приложения → «Сохранить проверку».
В карточке каждого запроса появится строка «Подпись: верна», «не сошлась» или «нет данных», а в раскрытой строке видно, что сравнивалось поле формы auth[application_token]. Чтобы чужие запросы получали отказ, добавьте правило: «+ Правило», условие «Подпись провайдера» → «верна» с отметкой «НЕ», действие «Статический ответ» с кодом 403. Под «НЕ верна» попадает и чужой токен, и запрос без токена. На бесплатном тарифе доступны 3 правила и проверка подписи.
Как получить сделку по ID из события
Поля сделки запрашиваются методом crm.item.get через входящий вебхук. entityTypeId для сделок — 2, для лидов — 1, для контактов — 3. Запрос в формате документации:
curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"entityTypeId":2,"id":7405}' \ "https://ваш-портал.bitrix24.ru/rest/1/секретный_код/crm.item.get"
Ответ — объект result.item, поля в camelCase: stageId, assignedById, updatedTime. Метод crm.deal.get тоже работает, но его развитие остановлено, и документация рекомендует crm.item.get.
Функция для фоновой задачи. Она различает три исхода: сделка есть, сделки уже нет, вызов не удался.
<?php // Поля сделки по ID из события: crm.item.get через входящий вебхук. // B24_REST — адрес входящего вебхука до имени метода: // https://ваш-портал.bitrix24.ru/rest/1/секретный_код/ // Возвращает null, если сделки уже нет: её могли удалить после события. function b24DealGet(int $id): ?array { $url = rtrim((string) getenv('B24_REST'), '/') . '/crm.item.get'; $body = json_encode(['entityTypeId' => 2, 'id' => $id]); for ($attempt = 1; ; $attempt++) { $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'], CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 60, // облачный Битрикс24 прерывает запрос через 60 с ]); $raw = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); $err = curl_error($ch); curl_close($ch); // В сообщения не попадает $url: в нём секретный код вебхука. if ($raw === false) { throw new RuntimeException("crm.item.get: $err"); } $res = json_decode($raw, true); if ($code === 200 && isset($res['result']['item'])) { return $res['result']['item']; } $error = $res['error'] ?? ''; if ($error === 'NOT_FOUND') { return null; } // Лимит интенсивности: документация советует повторять с растущей задержкой. if ($error === 'QUERY_LIMIT_EXCEEDED' && $attempt < 4) { sleep(2 ** ($attempt - 1)); // 1, 2, 4 с continue; } throw new RuntimeException("crm.item.get: HTTP $code $error"); } }
Функция проверена на заглушке, которая отвечает в формате документации: 200 с result.item → массив полей; 400 NOT_FOUND → null; дважды 503 QUERY_LIMIT_EXCEEDED, затем 200 → массив полей через 3 секунды; 503 на каждый вызов → исключение после четырёх попыток; 401 INVALID_CREDENTIALS → исключение сразу.
Почему лимиты здесь важны. В облачном Битрикс24 REST пропускает в среднем 2 запроса в секунду с запасом на всплеск до 50, на тарифе «Энтерпрайз» — 5 в секунду и 250. Лимит считается на портал и на IP-адрес отправителя: несколько ваших сервисов на одном сервере делят его между собой. Массовое изменение тысячи сделок даст тысячу событий. Если на каждое сразу вызывать crm.item.get, примерно после пятидесятого вызова пойдут ответы 503. Фоновая очередь с ограничением скорости решает это, а метод batch упаковывает до 50 вызовов в один HTTP-запрос.
Симптом → причина → что сделать
| Симптом | Причина и как проверить | Что сделать |
|---|---|---|
| Запрос не приходит ни разу | URL недоступен из интернета: localhost, внутренняя сеть, самоподписанный сертификат. Или портал в деморежиме. Проверка: временно поставьте в вебхук адрес hook.csap.ru и повторите действие | Публичный адрес с действительным сертификатом |
| На создание сделки приходит, на изменение нет | В вебхуке выбрано только ONCRMDEALADD | Добавить ONCRMDEALUPDATE |
| Коробочная версия, событий нет | Нет исходящего доступа к oauth.bitrix24.tech или фаервол обработчика не пускает серверы очередей. Проверка: curl -I https://oauth.bitrix24.tech/ с сервера Битрикс24 | Открыть доступ, адреса очередей брать из app.json |
| Запрос доходит до сервера, но не до кода | Прокси или WAF отбрасывает форму, либо адрес отвечает перенаправлением. Проверка с внешнего хоста: curl -i -d "test=1" https://ваш-адрес | Пропустить x-www-form-urlencoded; указать конечный адрес без редиректа |
| Обработчик видит пустое тело | Тело читают как JSON | $_POST, request.form, express.urlencoded({ extended: true }) |
Каждый запрос получает 403 | В B24_APP_TOKEN не тот секрет, например код входящего вебхука. Проверка: включите на адресе проверку подписи Битрикс24 с этим значением и посмотрите строку «Подпись» | Взять «Токен приложения» исходящего вебхука |
| События приходят всё реже | Обработчик отвечает медленно | Ответ 200 сразу, работа в фоне |
| Часть событий пропала | Обработчик не ответил или вернул ошибку, повторов нет. Проверка: логи обработчика за это время | Если потери недопустимы — приложение с офлайн-событиями, у вебхука их нет |
crm.item.get: 400 NOT_FOUND | Сделку удалили после события, или entityTypeId не тот: пришёл лид, а запрошена сделка | Считать штатным исходом; entityTypeId выбирать по коду события |
crm.item.get: 401 INVALID_CREDENTIALS | Нет активного входящего вебхука с таким кодом: его удалили или администратор отредактировал чужой вебхук, и код сменился. Ошибку авторизации даёт и вебхук с истёкшим сроком действия | Открыть входящий вебхук в портале, обновить адрес |
crm.item.get: 401 ACCESS_DENIED, REST is available only by subscription | REST API доступен только на коммерческих тарифах | Сменить тариф портала |
crm.item.get: 400 ACCESS_DENIED | У сотрудника, создавшего входящий вебхук, нет права читать сделку | Выдать права или создать вебхук от другого сотрудника |
crm.item.get: 503 QUERY_LIMIT_EXCEEDED | Превышен лимит интенсивности, обычно при массовом изменении | Очередь с ограничением скорости, batch, повтор с растущей задержкой |
Короткий чеклист
- Тело читается как форма, а не JSON.
auth[application_token]сравнивается за постоянное время; пустой или незаданный токен не пропускает запросы.- Обработчик отвечает
200сразу, работа — в фоновой задаче. - Поля сделки — через
crm.item.get, с обработкойNOT_FOUNDиQUERY_LIMIT_EXCEEDED. - Ни токен приложения, ни адрес входящего вебхука не попадают в логи.
Адрес для просмотра запросов открывается без регистрации на hook.csap.ru, тарифы с туннелем — на странице /pricing.
Проверено 10.10.2026 по документации Битрикс24 и на сервисе hook.csap.ru; лимиты тарифов сверены 17.10.2026.