# Подписки на события портала

Доставка событий Битрикс24 (например `ONTASKADD`, `ONTASKUPDATE`, `ONCRMDEALADD`) в приложение на Black Hole-сервере в реальном времени, без опроса. Платформа регистрирует обработчик события в Битрикс24 под OAuth-приложением сервера и доставляет каждое событие в приложение через туннель — с повторами и пробуждением спящего сервера.

Скоуп: `vibe:infra`

Управление подписками идёт по API-ключу, владеющему сервером. Приём событий не требует публичного URL: доставка управляемая и проходит через туннель Black Hole.

## Требования

Push-доставка работает только для сервера, привязанного к **ключу авторизации** `vibe_app_` — то есть к OAuth-приложению Битрикс24. Под обычным API-ключом `vibe_api_` или менеджмент-ключом `vibe_live_` обработчик события зарегистрировать нельзя, и создание подписки вернёт `400 NOT_OAUTH_APP`. Регистрация события в Битрикс24 доступна только на коммерческом тарифе — на бесплатном вернётся `502 BIND_FAILED`.

### Как получить сервер под ключом авторизации

Отдельной миграции существующего сервера с обычного ключа на ключ авторизации нет — сервер под ключом авторизации создаётся заново. Существующий сервер на `vibe_api_` или `vibe_live_` остаётся работать через опрос, перепривязать его к ключу авторизации «на месте» нельзя. Шаги:

1. **Создайте ключ авторизации.** `POST /v1/apps` или форма создания приложения в кабинете регистрирует OAuth-приложение на портале Битрикс24 и возвращает ключ `vibe_app_`. Вручную регистрировать приложение в Битрикс24 не нужно — платформа делает это за вас. Подробнее — [Ключи и авторизация](/docs/keys-auth).
2. **Авторизуйте приложение на портале.** Откройте или установите приложение на портале и пройдите OAuth-авторизацию. После этого Битрикс24 передаёт платформе `application_token` и пользовательский OAuth-токен. Без `application_token` создание подписки возвращает `400 NOT_OAUTH_APP`. Без пользовательского OAuth-токена — `400 NO_USER_TOKEN`. Поток авторизации — [Ключи и авторизация](/docs/keys-auth).
3. **Создайте новый сервер под этим ключом.** `POST /v1/infra/servers` с ключом `vibe_app_` — сервер будет привязан к OAuth-приложению.
4. **Перенесите приложение** на новый сервер обычным деплоем ([Деплой](/docs/infra/deploy)) и подпишитесь на события.

Ответы `400 NOT_OAUTH_APP` и `400 NO_USER_TOKEN` содержат поле `hint` с этими же шагами — на случай, если до подписки вы дошли через API.

## Операции

- [Создать подписку](./event-subscriptions/create.md) — `POST /v1/infra/servers/:id/event-subscriptions`
- [Список подписок](./event-subscriptions/list.md) — `GET /v1/infra/servers/:id/event-subscriptions`
- [Удалить подписку](./event-subscriptions/delete.md) — `DELETE /v1/infra/servers/:id/event-subscriptions/:subId`

## Возможности

- [Обработчик на стороне приложения](./event-subscriptions/handler.md)

## Типовой сценарий

1. Создайте сервер под ключом авторизации `vibe_app_` (см. «Требования») и перенесите на него приложение.
2. Создайте подписку: [`POST /v1/infra/servers/:id/event-subscriptions`](./event-subscriptions/create.md) с кодом события и путём обработчика.
3. Реализуйте [обработчик](./event-subscriptions/handler.md): примите событие, сверьте `auth[application_token]`, ответьте `2xx`. Для вызовов V1 API из обработчика используйте персональный ключ `vibe_api_`.
4. Проверьте доставки: [`GET /v1/infra/servers/:id/event-subscriptions`](./event-subscriptions/list.md) — массив `recentDeliveries` показывает статусы и ошибки последних доставок.

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

- [Серверы](/docs/infra/servers)
- [Deploy API](/docs/infra/deploy)
- [Ключи и авторизация](/docs/keys-auth)
- [Инфраструктура](/docs/infra)
- [Ошибки](/docs/errors)