Создать подписку

POST /v1/infra/servers/:id/event-subscriptions

Регистрирует обработчик события Битрикс24 под OAuth-приложением сервера. После создания платформа доставляет каждое событие указанного типа в приложение по пути appPath. Сервер должен быть привязан к ключу авторизации vibe_app_ — предусловия и порядок создания такого сервера описаны в разделе Подписки на события портала.

Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера. Список: `GET /v1/infra/servers`

Поля запроса (body)

Поле Тип Обяз. Описание
event string да Код события Битрикс24. Формат ^[A-Z][A-Z0-9_]+$ — заглавные латинские буквы, цифры, подчёркивание. Примеры: ONTASKADD, ONTASKUPDATE, ONCRMDEALADD
appPath string да Путь на приложении, куда доставлять событие. Начинается с /. Пример: /api/webhooks/b24

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/event-subscriptions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "ONTASKADD", "appPath": "/api/webhooks/b24" }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/event-subscriptions \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event": "ONTASKADD", "appPath": "/api/webhooks/b24" }'

JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/event-subscriptions`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ event: 'ONTASKADD', appPath: '/api/webhooks/b24' }),
  }
)
const { success, data } = await res.json()
console.log('ID подписки:', data.id, '— обработчик:', data.b24Handler)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/event-subscriptions`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ event: 'ONTASKADD', appPath: '/api/webhooks/b24' }),
  }
)
const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean true при успехе
data.id string (UUID) ID подписки
data.appId string ID OAuth-приложения, под которым зарегистрирован обработчик
data.serverId string (UUID) ID сервера
data.portalId string ID портала Битрикс24
data.event string Код события
data.appPath string Путь доставки на приложении
data.authType string ID пользователя-установщика приложения в Битрикс24
data.b24Handler string URL обработчика на платформе, куда Битрикс24 шлёт событие
data.status string Статус подписки: ACTIVE, DISABLED, DEGRADED. DEGRADED — после серии неудачных доставок
data.createdById string | null ID пользователя Вайбкод, создавшего подписку
data.createdAt string Дата создания (ISO 8601)
data.updatedAt string Дата последнего изменения (ISO 8601)

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "appId": "9a1c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "serverId": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "event": "ONTASKADD",
    "appPath": "/api/webhooks/b24",
    "authType": "1",
    "b24Handler": "https://vibecode.bitrix24.tech/v1/portal-events/9a1c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "ACTIVE",
    "createdById": "7f3a1c2b-9d8e-4a6f-b1c2-3d4e5f6a7b8c",
    "createdAt": "2026-06-07T10:00:00.000Z",
    "updatedAt": "2026-06-07T10:00:00.000Z"
  }
}

Пример ответа при ошибке

400 — сервер не привязан к OAuth-приложению:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_OAUTH_APP",
    "message": "Server is not backed by an OAuth app with a B24 application token"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_EVENT Код события пуст или не соответствует формату ^[A-Z][A-Z0-9_]+$
400 INVALID_APP_PATH appPath не начинается с / либо содержит управляющие символы
400 NOT_OAUTH_APP Сервер не привязан к OAuth-приложению с application_token. Ответ содержит поле hint с порядком создания такого сервера
400 NO_USER_TOKEN У приложения нет OAuth-токена — сначала авторизуйте приложение на портале. Ответ содержит поле hint
404 NOT_FOUND Сервер не найден или принадлежит другому API-ключу
409 EVENT_BOUND_ELSEWHERE Это событие уже привязано к другому серверу того же приложения — сначала удалите прежнюю подписку
502 BIND_FAILED Битрикс24 отклонил регистрацию события — например, портал не на коммерческом тарифе

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Повторный вызов с той же парой (сервер, событие) обновляет подписку. Если подписка на это событие уже есть на этом же сервере, повторный вызов обновляет appPath и возвращает 200 — подходит для перезапуска скриптов настройки.

Смотрите также