B24Hook

Class for secure interaction with the Bitrix24 REST API from server-side code. Contains methods for creating authorized requests via webhooks. Works only in server environment.

The B24Hook object is intended exclusively for use on the server.

A webhook contains a secret access key, which MUST NOT be used in client-side code (browser, mobile app).
For the client side, use B24Frame.

Quick Overview

B24Hook is the main SDK class for working with the Bitrix24 REST API via webhooks. A webhook is a special URL that has authentication data (user ID and secret key) embedded in it. This allows making API requests without additional authorization.

Creating a B24Hook Instance

There are two ways to create a B24Hook instance:

From a Full Webhook URL

Use this method (recommended approach) if you have a ready-made webhook URL generated in Bitrix24.

import { B24Hook } from '@bitrix24/b24jssdk'

// Creating an instance from a full webhook URL
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

Method Signature

static fromWebhookUrl(
  url: string
): B24Hook

Parameters

Parameter	Type	Description
`url`	`string`	Full webhook URL. Example: `https://company.bitrix24.com/rest/1/k32t88gf3azpmwv3/`

When to use:

For rapid prototyping
When the webhook URL is stored in server environment variables

From Parameters

Use this method if webhook parameters are stored separately.

import { B24Hook } from '@bitrix24/b24jssdk'

// Creating an instance from individual parameters
const $b24 = new B24Hook({
  b24Url: 'https://your_domain.bitrix24.com',
  userId: 1,
  secret: 'webhook_code'
})

Constructor Signature

constructor(
  b24HookParams: B24HookParams
)

Parameters

B24HookParams is an interface with the following fields:

Parameter	Type	Description
`b24Url`	`string`	Bitrix24 portal URL. Example: `https://company.bitrix24.com`
`userId`	`number`	ID of the user for whom the webhook was created
`secret`	`string`	Webhook secret key

When to use:

When webhook parameters are stored in different environment variables

Example

TestConnection.ts

import { B24Hook } from '@bitrix24/b24jssdk'

// Method 1: From an environment variable with a full URL
const webhookUrl = process.env.BITRIX24_WEBHOOK_URL
const $b24 = B24Hook.fromWebhookUrl(webhookUrl!)

// Method 2: From separate environment variables
// const $b24 = new B24Hook({
//   b24Url: process.env.BITRIX24_URL!,
//   userId: Number.parseInt(process.env.BITRIX24_USER_ID!),
//   secret: process.env.BITRIX24_WEBHOOK_SECRET!
// })

// Example of using the created instance
async function testConnection(): Promise<boolean> {
  try {
    // Check the connection by requesting server time information
    const response = await $b24.callMethod('server.time')

    if (!response.isSuccess) {
      throw new Error(`Connection error: ${response.getErrorMessages().join('; ')}`)
    }

    const serverTime = response.getData().result
    console.log(`Connected to Bitrix24: time ${serverTime}`)
    return true
  } catch (error) {
    console.error('Problem connecting:', error)
    return false
  }
}

// Start connection check
const isConnected = await testConnection()
if (isConnected) {
  console.log('B24Hook successfully initialized')
}

Recommendations for Storing Webhook Data

// ✅ Storing in server environment variables
const $b24 = B24Hook.fromWebhookUrl(process.env.BITRIX24_WEBHOOK_URL!);


// ❌ NEVER store a webhook in client code
// ❌ NEVER commit a webhook to Git
const $b24 = B24Hook.fromWebhookUrl(
  'https://company.bitrix24.com/rest/1/abcdef123456/'
); // DATA LEAK!

What to Do Next

After creating a B24Hook instance, you can use the following methods:

Core API methods:

callMethod() — Call any REST API method
callBatch() — Batch execution of up to 50 commands

Working with lists:

callFastListMethod() — Automatic retrieval of all list pages
fetchListMethod() — Incremental loading of large lists via generator

Advanced scenarios:

callBatchByChunk() — Batch execution of any number of commands with automatic chunking

FAQ

callMethod

The primary method for executing Bitrix24 REST API calls via webhook. Allows calling any REST API method with specified parameters. Works only in a server environment. Works only in server environment.