#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.
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.
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) 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 order 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

For the full list of common API errors, see 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