# Bitrix24 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 for 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

You can switch an existing server to an authorization key in your Vibecode account — "Change managing key" on the server card in the "Black Hole Servers" section. The authorization key of a live application is accepted there when that application does not own a server yet. If there is no server at all, create one under the right key straight away:

1. **Create an authorization key.** `POST /v1/apps` or the application-creation form in the Vibecode dashboard registers an OAuth application in your 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 in your Bitrix24 account.** Open or install the application in your 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`. For the authorization flow, see [Keys and authorization](/docs/keys-auth).
3. **Bind a server to this key.** Either create a new one — `POST /v1/infra/servers` with a `vibe_app_` key — or change the managing key of an existing one in your Vibecode account ([Restoring access to a server](/docs/infra/server-access-recovery)).
4. **Deploy the application** 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. Bind a server to a `vibe_app_` authorization key — create a new one or change the managing key of an existing one (see "Requirements") — and deploy the application onto 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)