Для AI-агентов: markdown этой страницы — /docs-content/infra/bizproc-callbacks.md индекс документации — /llms.txt
Доставка вызовов действий и роботов
Обработчик действия или робота на субдомене Black Hole получает надёжную доставку: платформа ставит вызовы в очередь, будит спящий сервер и повторяет попытки. Обработчик на своём домене работает по-прежнему — Битрикс24 обращается к нему напрямую и повторных попыток не делает.
Скоуп: bizproc
Отдельного эндпоинта у механизма нет. Он включается сам, когда вы указываете адрес на субдомене Black Hole в поле handler — при регистрации действия, регистрации робота или при смене обработчика у уже заведённых.
Что происходит при регистрации
Платформа сопоставляет субдомен из handler с сервером вашего приложения и запоминает привязку — приложение, код действия или робота, сервер и путь обработчика. В Битрикс24 при этом сохраняется адрес приёмника платформы, а не переданный вами. Так и задумано: вызов приходит на приёмник, платформа доставляет его в приложение по тому же пути, который вы указали в handler. Из адреса берётся только путь — строка запроса после ? в доставку не попадает, передавайте нужные значения отдельным путём обработчика.
Коды действий и роботов живут в разных реестрах, поэтому один и тот же code может быть зарегистрирован и действием, и роботом: платформа держит для них две отдельные привязки и не путает вызовы.
Если субдомена не существует, сервер за ним удалён или принадлежит другому приложению, регистрация отклоняется отказом 400 SERVER_APP_MISMATCH. Регистрируйте обработчик ключом того приложения, к которому привязан сервер.
Что приходит в обработчик
Платформа отправляет вызов POST-запросом на путь обработчика в формате application/x-www-form-urlencoded. Тело — ровно то, что прислал бы Битрикс24 при прямом вызове, включая auth[application_token] и code: обработчик, написанный под прямой вызов, менять не нужно.
Ответ платформа ждёт до 10 секунд — это окно уже, чем 30 секунд, которые даёт приложению шлюз на запросе через субдомен. Ответ 2xx считается доставкой, любой другой ответ или молчание — поводом повторить. Тяжёлую работу выносите в фон и отвечайте сразу.
Повтор приходит с тем же телом, поэтому обработчик должен быть готов увидеть уже обработанный вызов: приложение, которое ответило на двенадцатой секунде, свою работу выполнило, а платформа этого ответа не дождалась и вызов повторит. Отсеивайте повторы по workflow_id или event_token.
Когда повторы заканчиваются
Повторы не бесконечны. Если доставка так и не удалась — приложение не ответило 2xx, сервер не поднялся или его удалили, — платформа сообщает владельцу сервера в чат Битрикс24 и перестаёт доставлять вызовы этого обработчика. Следующие вызовы Битрикс24 приёмник примет, но до приложения они не дойдут, и повторного сообщения не будет. Доставка возобновляется, когда вы регистрируете обработчик заново или обновляете его с полем handler.
Смена обработчика
Смена handler на субдомен Black Hole переключает действие или робота на надёжную доставку. Обратная смена — на адрес своего домена — возвращает прямые вызовы без повторов.
Запрос без поля handler привязку не меняет: обновление любых других полей оставляет доставку такой, какой она была после регистрации.
Регистрация идёт одиночным запросом
Обработчик на субдомене Black Hole регистрируется и меняется только одиночным вызовом — платформе нужен отдельный запрос, чтобы завести доставку. Пакетный вызов такую регистрацию отклоняет, и форма отказа зависит от того, куда отправлен пакет.
| Куда отправлен пакет | Что приходит |
|---|---|
POST /v1/batch |
BIZPROC_CALLBACK_BATCH_UNSUPPORTED в data.errors под id этого вызова. Остальные вызовы пакета выполняются, а если других вызовов в пакете нет — весь запрос отвечает 400 |
POST /v1/{entity}/batch |
400 BATCH_ITEM_VALIDATION на весь пакет. Имя BIZPROC_CALLBACK_BATCH_UNSUPPORTED и индекс элемента приходят внутри message |
Обработчик на своём домене проходит пакетным вызовом в обоих случаях.
Включение по аккаунтам
Надёжная доставка включается по аккаунтам. Пока она не включена на вашем аккаунте, регистрация проходит как прежде: адрес обработчика остаётся вашим, вызовы приходят от Битрикс24 напрямую. Отказ SERVER_APP_MISMATCH и запрет пакетной регистрации действуют только при включённой доставке.
Публичный режим и авто-сон
Публичный режим для вызовов действий и роботов не нужен никогда: такой вызов проходит проверку доступа по своему признаку, при любой политике сервера.
Отключать авто-сон тоже не нужно, но только при включённой надёжной доставке: вызов приходит на приёмник платформы, она сама будит спящий сервер и довозит вызов через туннель. Пока доставка на аккаунте не включена, Битрикс24 обращается к субдомену напрямую, и вызов, пришедший на спящий сервер, теряется — повторов у прямого вызова нет. До включения держите сервер онлайн, как для событий Битрикс24.
Коды отказов каждой операции перечислены на её странице, полный список общих ошибок API — Ошибки.