# Portal event subscriptions

Real-time delivery of Bitrix24 events (for example `ONTASKADD`, `ONTASKUPDATE`, `ONCRMDEALADD`) to an application on a Black Hole server, without polling. The platform registers an event handler in Bitrix24 under the server's OAuth application and delivers each event to the application through the tunnel — with retries and wake-up of a sleeping server.

Scope: `vibe:infra`

Subscriptions are managed by the API key that owns the server. Receiving events does not require a public URL: delivery is managed and passes through the Black Hole tunnel.

## Requirements

Push delivery works only for a server bound to a `vibe_app_` **authorization key** — that is, to a Bitrix24 OAuth application. Under a regular `vibe_api_` API key or a `vibe_live_` management key you cannot register an event handler, and creating a subscription returns `400 NOT_OAUTH_APP`. Registering an event in Bitrix24 is available only on a commercial plan — on the free plan it returns `502 BIND_FAILED`.

### How to get a server under an authorization key

There is no separate migration of an existing server from a regular key to an authorization key — a server under an authorization key is created from scratch. An existing server on `vibe_api_` or `vibe_live_` keeps working through polling, and it cannot be re-bound to an authorization key "in place". Steps:

1. **Create an authorization key.** `POST /v1/apps` or the application-creation form in the dashboard registers an OAuth application on the Bitrix24 account and returns a `vibe_app_` key. You do not need to register the application in Bitrix24 manually — the platform does it for you. See [Keys and authorization](/docs/keys-auth).
2. **Authorize the application on the Bitrix24 account.** Open or install the application on the Bitrix24 account and complete OAuth authorization. After that Bitrix24 passes the platform an `application_token` and a user OAuth token. Without `application_token`, creating a subscription returns `400 NOT_OAUTH_APP`. Without a user OAuth token — `400 NO_USER_TOKEN`. The authorization flow — [Keys and authorization](/docs/keys-auth).
3. **Create a new server under this key.** `POST /v1/infra/servers` with a `vibe_app_` key — the server will be bound to the OAuth application.
4. **Move the application** to the new server via a regular deploy ([Deploy](/docs/infra/deploy)) and subscribe to events.

The `400 NOT_OAUTH_APP` and `400 NO_USER_TOKEN` responses contain a `hint` field with these same steps — in case you reached the subscription step via the API.

## Operations

- [Create subscription](./event-subscriptions/create.md) — `POST /v1/infra/servers/:id/event-subscriptions`
- [List subscriptions](./event-subscriptions/list.md) — `GET /v1/infra/servers/:id/event-subscriptions`
- [Delete subscription](./event-subscriptions/delete.md) — `DELETE /v1/infra/servers/:id/event-subscriptions/:subId`

## Capabilities

- [Application-side handler](./event-subscriptions/handler.md)

## Typical scenario

1. Create a server under a `vibe_app_` authorization key (see "Requirements") and move the application to it.
2. Create a subscription: [`POST /v1/infra/servers/:id/event-subscriptions`](./event-subscriptions/create.md) with an event code and a handler path.
3. Implement the [handler](./event-subscriptions/handler.md): accept the event, verify `auth[application_token]`, respond with `2xx`. For V1 API calls from the handler use a personal `vibe_api_` key.
4. Check deliveries: [`GET /v1/infra/servers/:id/event-subscriptions`](./event-subscriptions/list.md) — the `recentDeliveries` array shows the statuses and errors of the latest deliveries.

## See also

- [Servers](/docs/infra/servers)
- [Deploy API](/docs/infra/deploy)
- [Keys and authorization](/docs/keys-auth)
- [Infrastructure](/docs/infra)
- [Errors](/docs/errors)