B24Hook Class

Overview

B24Hook is the SDK class for working with the Bitrix24 REST API through an inbound webhook. A webhook is a URL that already carries the user identifier and a secret token, so requests authenticate without an OAuth handshake.

The class extends AbstractB24 and implements TypeB24, so the full REST surface (actions.v2.*, actions.v3.*, tools.*) is available immediately after construction — there is no await b24.init() step.

Creating a B24Hook Instance

There are two ways to create a B24Hook instance.

From a Full Webhook URL

Recommended approach when the webhook URL is stored as a single environment variable.

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/k32t88gf3azpmwv3/')

Method Signature

static fromWebhookUrl(
  url: string,
  options?: { restrictionParams?: Partial<RestrictionParams> }
): B24Hook

Parameters

The static factory validates the URL: HTTPS is required, the path must match one of the supported shapes, and the user id must be numeric. Anything else throws synchronously.

From Parameters

Use this constructor when webhook parts are stored separately (for example: portal URL in one env var, token in a secrets manager).

import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = new B24Hook({
  b24Url: 'https://your_domain.bitrix24.com',
  userId: 1,
  secret: 'k32t88gf3azpmwv3'
})

Constructor Signature

constructor(
  b24HookParams: B24HookParams,
  options?: { restrictionParams?: Partial<RestrictionParams> }
)

B24HookParams Fields

Quick Example

import { B24Hook, EnumCrmEntityTypeId, LoggerFactory } from '@bitrix24/b24jssdk'

const $logger = LoggerFactory.createForBrowser('node:hook', process.env.NODE_ENV === 'development')

if (!process.env.B24_HOOK) {
  throw new Error('B24_HOOK env variable is required')
}

const $b24 = B24Hook.fromWebhookUrl(process.env.B24_HOOK)

const response = await $b24.actions.v2.call.make<{ id: number, title: string }>({
  method: 'crm.item.list',
  params: {
    entityTypeId: EnumCrmEntityTypeId.company,
    select: ['id', 'title']
  },
  requestId: 'companies-list'
})

if (!response.isSuccess) {
  $logger.error('REST error', { messages: response.getErrorMessages() })
  process.exit(1)
}

$logger.info('Companies', response.getData()?.result)

Getters

auth

get auth(): AuthActions

Returns the AuthHookManager instance, which implements AuthActions:

• getAuthData() — returns synthetic AuthData composed from the webhook secret. expires is always 0 (webhook tokens do not expire).
• refreshAuth() — for compatibility with B24OAuth; returns the same data without performing a network call.
• getUniq(prefix: string) — returns <prefix>_<member_id>, used by the Pull client and other helpers.
• isAdmin — always true (webhooks are assumed to be created by admins).

isInit

get isInit(): boolean

Always true immediately after construction — no init() call is required for B24Hook.

actions / tools

Same shape as on every TypeB24 class. See:

• CallV2.make / CallV3.make
• CallListV2.make / CallListV3.make
• FetchListV2.make / FetchListV3.make
• BatchV2.make / BatchV3.make
• BatchByChunkV2.make / BatchByChunkV3.make
• tools.healthCheck.make, tools.ping.make

Methods

getTargetOrigin

getTargetOrigin(): string

Returns the portal origin (https://your_domain.bitrix24.com).

getTargetOriginWithPath

getTargetOriginWithPath(): Map<ApiVersion, string>

Returns the per-version REST endpoint:

• ApiVersion.v2 → https://your_domain.bitrix24.com/rest/<userId>/<secret>
• ApiVersion.v3 → https://your_domain.bitrix24.com/rest/api/<userId>/<secret>

offClientSideWarning

offClientSideWarning(): void

Disables the runtime warning emitted by both HTTP clients when B24Hook is detected in a browser environment. Use only when you intentionally proxy the webhook through a server-side wrapper that strips the secret before any browser request.

getHttpClient / setHttpClient

getHttpClient(version: ApiVersion): TypeHttp
setHttpClient(version: ApiVersion, client: TypeHttp): void

Direct access to the underlying HTTP transports (one per REST API version). See Http reference.

setRestrictionManagerParams

setRestrictionManagerParams(params: RestrictionParams): Promise<void>

Replaces the rate-limit / operating-limit / adaptive-delay configuration on both v2 and v3 clients at once. See Limiters.

getLogger / setLogger

getLogger(): LoggerInterface
setLogger(logger: LoggerInterface): void

Get or replace the logger used by the SDK and propagated into the HTTP clients. See Logger.

destroy

destroy(): void

Releases internal references. Call before the process exits or when discarding a long-lived instance.

function shutdown() {
  $b24.destroy()
}

Storing the Webhook Secret

// @check-ignore: partial snippet — illustrates env vs inline URL pattern

// ✅ Server-side env variable
const $b24ok = B24Hook.fromWebhookUrl(process.env.BITRIX24_WEBHOOK_URL!)

// ❌ Never inline the URL in client code or commit it to Git
const $b24bad = B24Hook.fromWebhookUrl(
  'https://company.bitrix24.com/rest/1/abcdef123456/'
)

FAQ