Исходящий вебхук Битрикс24: что приходит в запросе и как проверить токен

Исходящий вебхук Битрикс24 шлёт форму, а не JSON, и только ID объекта. Проверка application_token, crm.item.get, лимиты REST и таблица ошибок.

Опубликовано Обновлено 18 минут чтения

  • битрикс24
  • вебхуки
  • crm
  • исходящий вебхук
  • rest api
Исходящий вебхук Битрикс24 деревом полей в ленте hook.csap.ru

Исходящий вебхук Битрикс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_idID подписки; через REST его не узнать, но он удобен как метка в логах
data[FIELDS][ID]ID сделки, лида или другого объекта CRM — строкой
tsUnix-время в секундах
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:

  1. Откройте раздел «Приложения» → «Разработчикам».
  2. Перейдите на вкладку «Готовые сценарии» → «Другое» → «Исходящий вебхук».
  3. Укажите URL обработчика.
  4. Выберите одно или несколько событий, например ONCRMDEALADD.
  5. Нажмите «Создать». В форме появится поле «Токен приложения» — сохраните его значение.
  6. Проверьте вызов: создайте или измените сделку.

Ограничения:

  • 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:

  1. Откройте hook.csap.ru и нажмите «Открыть мой адрес». Регистрация не нужна.
  2. Скопируйте адрес вида https://hook.csap.ru/t/ВАШ_ТОКЕН и допишите путь, например /b24.
  3. Вставьте адрес в поле URL исходящего вебхука. Начинайте с https://: на http:// сервис отвечает перенаправлением 301.
  4. Создайте сделку.

Ниже — запрос из примера документации, отправленный на адрес сервиса. Снимки сделаны на тестовом стенде сервиса, а не на настоящем портале. Форма разобрана в дерево: ключ 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
<?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 ключи формы плоские: скобки остаются частью имени.

python
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]"].

javascript
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):

ЗапросPHPFlaskExpress
форма из документации, верный токен200200200
чужой токен403403403
без auth[application_token]403403403
JSON вместо формы403403403
токен массивом auth[application_token][]403403403
B24_APP_TOKEN не задан500не запускаетсяне запускается

Если один обработчик принимает события от нескольких порталов, документация советует хранить токен вместе с auth[member_id] и искать сохранённый токен по нему. Сам токен — секрет: в логи и сообщения об ошибках он попадать не должен.

Отладка на своём компьютере

Портал не отправит запрос на localhost. Укажите в вебхуке адрес hook.csap.ru и включите туннель: запрос на …/t/ВАШ_ТОКЕН/b24 уйдёт на http://localhost:3000/b24, а ответ обработчика получит Битрикс24. Для туннеля нужен вход в аккаунт, на бесплатном тарифе доступна одна сессия.

bash
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. Запрос в формате документации:

bash
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
<?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 subscriptionREST 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.

Все руководства
Строка доставки в ленте hook.csap.ru: повтор 3, ответ 502, следующая попытка через 3 минуты

Вебхук пришёл, а ваш сервер лежал: пересылка с повторами

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

  • пересылка
  • повторы
  • доставка вебхуков
  • надёжность
  • битрикс24
  • тильда
  • amocrm
Cookie и Яндекс Метрика

Мы хотим подключить Яндекс Метрику: она ставит cookie и помогает понять, как посетители пользуются сайтом. Метрика заработает, только если вы разрешите. Без неё сервис работает так же. Политика обработки данных