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

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

Регистрирует обработчик события Битрикс24 под OAuth-приложением сервера. После создания платформа доставляет каждое событие указанного типа в приложение по пути `appPath`. Сервер должен быть привязан к ключу авторизации `vibe_app_` — предусловия и порядок создания такого сервера описаны в разделе [Подписки на события портала](/docs/infra/event-subscriptions).

## Параметры

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

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

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

## Примеры

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

```bash
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-приложение

```bash
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` |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `NOT_FOUND` | Сервер не найден или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 409 | `EVENT_BOUND_ELSEWHERE` | Это событие уже привязано к другому серверу того же приложения — сначала удалите прежнюю подписку |
| 502 | `BIND_FAILED` | Битрикс24 отклонил регистрацию события — например, портал не на коммерческом тарифе |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

- [Подписки на события портала](/docs/infra/event-subscriptions)
- [Список подписок](/docs/infra/event-subscriptions/list)
- [Обработчик на стороне приложения](/docs/infra/event-subscriptions/handler)
- [Ключи и авторизация](/docs/keys-auth)
- [Ошибки](/docs/errors)