For AI agents: markdown of this page — /docs-content-en/infra/event-subscriptions/create.md documentation index — /llms.txt

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 appPath. 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 Bitrix24 event subscriptions section.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionServer ID. List: GET /v1/infra/servers

Request fields (body)

Field Type Required Description
Fieldevent Typestring Requiredyes DescriptionBitrix24 event code. Format ^[A-Z][A-Z0-9_]+(?:\.[A-Z][A-Z0-9_]+)*$ — uppercase Latin letters, digits and underscores. Code parts are separated by dots. Examples: ONTASKADD, ONCRMDEALADD, CATALOG.PRODUCT.ON.ADD
FieldappPath Typestring Requiredyes DescriptionPath on the application where the event is delivered. Starts with /. Example: /api/webhooks/b24

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typestring (UUID) DescriptionSubscription ID
Fielddata.appId Typestring DescriptionID of the OAuth application the handler is registered under
Fielddata.serverId Typestring (UUID) DescriptionServer ID
Fielddata.portalId Typestring DescriptionBitrix24 portal ID
Fielddata.event Typestring DescriptionEvent code
Fielddata.appPath Typestring DescriptionDelivery path on the application
Fielddata.authType Typestring DescriptionBitrix24 ID of the user who installed the application
Fielddata.b24Handler Typestring DescriptionHandler URL on the platform where Bitrix24 sends the event
Fielddata.status Typestring DescriptionSubscription status: ACTIVE, DISABLED, DEGRADED. DEGRADED — after a series of failed deliveries
Fielddata.createdById Typestring | null DescriptionID of the Vibecode user who created the subscription
Fielddata.createdAt Typestring DescriptionCreation date (ISO 8601)
Fielddata.updatedAt Typestring DescriptionLast modification date (ISO 8601)

Response example

JSON 
{
  "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:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_EVENT DescriptionThe event code is empty or does not match the format ^[A-Z][A-Z0-9_]+(?:\.[A-Z][A-Z0-9_]+)*$
HTTP400 CodeINVALID_APP_PATH DescriptionappPath does not start with / or contains control characters
HTTP400 CodeNOT_OAUTH_APP DescriptionThe server is not backed by an OAuth application with an application_token. The response contains a hint field with the steps for creating such a server
HTTP400 CodeNO_USER_TOKEN DescriptionThe application has no OAuth token — authorize the application on the portal first. The response contains a hint field
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
HTTP403 CodeSERVER_ROLE_FORBIDDEN DescriptionYou are on this server's development team with the Developer role, and this operation is open to the Administrator role. error.hint carries your role, the required threshold and the list of calls that are open to you. Role breakdown — List servers
HTTP404 CodeNOT_FOUND DescriptionThe server does not exist or belongs to another API key while you are not on its development team
HTTP409 CodeEVENT_BOUND_ELSEWHERE DescriptionThis event is already bound to another server of the same application — delete the previous subscription first
HTTP502 CodeBIND_FAILED DescriptionBitrix24 rejected the event registration — for example, the portal is not on a commercial plan

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 — useful for re-running setup scripts.
  • The Bitrix24 tokens in the event body depend on the mode of the server key and the app key, and on the app address. If either key does not change Bitrix24 data, or the app address appUrl points outside the platform, the subscription's events arrive without auth[access_token] and auth[refresh_token] — see Event body.

See also