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 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

Parameter In Type Required Description
id path string (UUID) yes Server ID. List: GET /v1/infra/servers

Request fields (body)

Field Type Required Description
event string yes Bitrix24 event code. Format ^[A-Z][A-Z0-9_]+$ — uppercase Latin letters, digits, underscore. Examples: ONTASKADD, ONTASKUPDATE, ONCRMDEALADD
appPath string yes Path 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
success boolean true on success
data.id string (UUID) Subscription ID
data.appId string ID of the OAuth application the handler is registered under
data.serverId string (UUID) Server ID
data.portalId string Bitrix24 portal ID
data.event string Event code
data.appPath string Delivery path on the application
data.authType string Bitrix24 ID of the user who installed the application
data.b24Handler string Handler URL on the platform where Bitrix24 sends the event
data.status string Subscription status: ACTIVE, DISABLED, DEGRADED. DEGRADED — after a series of failed deliveries
data.createdById string | null ID of the Vibecode user who created the subscription
data.createdAt string Creation date (ISO 8601)
data.updatedAt string Last change 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
400 INVALID_EVENT The event code is empty or does not match the format ^[A-Z][A-Z0-9_]+$
400 INVALID_APP_PATH appPath does not start with / or contains control characters
400 NOT_OAUTH_APP The server is not backed by an OAuth application with an application_token. The response contains a hint field with the order for creating such a server
400 NO_USER_TOKEN The application has no OAuth token — authorize the application on the portal first. The response contains a hint field
404 NOT_FOUND The server was not found or belongs to another API key
409 EVENT_BOUND_ELSEWHERE This event is already bound to another server of the same application — delete the previous subscription first
502 BIND_FAILED Bitrix24 rejected the event registration — for example, the portal is not on a commercial plan

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