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 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.
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.
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).
4. Deploy the application via a regular deploy (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.

Create a subscription

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

Registers a Bitrix24 event handler under the server's OAuth application. After creation, the platform delivers every event of the specified type to the application at the appPath path. The server must be backed by a vibe_app_ authorization key — the prerequisites and the steps for creating such a server are described in the Portal event subscriptions section.

Parameters

Request fields (body)

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/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 application

curl -X POST https://vibecode.bitrix24.com/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 — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/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('Subscription ID:', data.id, '— handler:', data.b24Handler)

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/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()

Response fields

Response example

{
  "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.com/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"
  }
}

Error response example

400 — the server is not backed by an OAuth application:

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

Errors

Full list of common API errors — Errors.

Known specifics

• Calling again with the same (server, event) pair updates the subscription. If a subscription for this event already exists on the same server, calling again updates appPath and returns 200 — suitable for re-running setup scripts.

See also

• Portal event subscriptions
• List subscriptions
• Application-side handler
• Keys and authorization
• Errors