Класс B24Hook

Обзор

B24Hook — это класс SDK для работы с REST API Bitrix24 через входящий вебхук. Вебхук — это URL, который уже содержит идентификатор пользователя и секретный токен, поэтому запросы аутентифицируются без OAuth-рукопожатия.

Класс наследуется от AbstractB24 и реализует TypeB24, поэтому полный набор REST-методов (actions.v2.*, actions.v3.*, tools.*) доступен сразу после создания экземпляра — шаг await b24.init() не требуется.

Создание экземпляра B24Hook

Создать экземпляр B24Hook можно двумя способами.

Из полного URL вебхука

Рекомендуемый способ, когда URL вебхука хранится в одной переменной окружения.

import { B24Hook } from '@bitrix24/b24jssdk'

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

Сигнатура метода

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

Параметры

Статическая фабрика валидирует URL: требуется HTTPS, путь должен соответствовать одному из поддерживаемых форматов, а идентификатор пользователя должен быть числовым. Всё остальное синхронно выбрасывает исключение.

Из параметров

Используйте этот конструктор, когда части вебхука хранятся раздельно (например: URL портала в одной переменной окружения, токен — в менеджере секретов).

import { B24Hook } from '@bitrix24/b24jssdk'

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

Сигнатура конструктора

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

Поля B24HookParams

Быстрый пример

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)

Геттеры

auth

get auth(): AuthActions

Возвращает экземпляр AuthHookManager, который реализует AuthActions:

• getAuthData() — возвращает синтетический AuthData, собранный из секрета вебхука. expires всегда равен 0 (токены вебхуков не истекают).
• refreshAuth() — для совместимости с B24OAuth; возвращает те же данные без сетевого запроса.
• getUniq(prefix: string) — возвращает <prefix>_<member_id>, используется Pull-клиентом и другими хелперами.
• isAdmin — всегда true (предполагается, что вебхуки создаются администраторами).

isInit

get isInit(): boolean

Всегда true сразу после создания экземпляра — вызов init() для B24Hook не требуется.

actions / tools

Та же структура, что и у каждого класса TypeB24. См.:

• 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

Методы

getTargetOrigin

getTargetOrigin(): string

Возвращает origin портала (https://your_domain.bitrix24.com).

getTargetOriginWithPath

getTargetOriginWithPath(): Map<ApiVersion, string>

Возвращает 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

Отключает runtime-предупреждение, которое оба HTTP-клиента выводят при обнаружении B24Hook в браузерном окружении. Используйте только если вы намеренно проксируете вебхук через серверную обёртку, которая удаляет секрет до любого запроса из браузера.

getHttpClient / setHttpClient

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

Прямой доступ к нижележащим HTTP-транспортам (по одному на каждую версию REST API). См. справочник Http.

setRestrictionManagerParams

setRestrictionManagerParams(params: RestrictionParams): Promise<void>

Заменяет конфигурацию rate limit / operating limit / адаптивной задержки сразу на клиентах v2 и v3. См. Лимитеры.

getLogger / setLogger

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

Получает или заменяет логгер, используемый SDK и передаваемый в HTTP-клиенты. См. Логгер.

destroy

destroy(): void

Освобождает внутренние ссылки. Вызывайте перед завершением процесса или при удалении долгоживущего экземпляра.

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

Хранение секрета вебхука

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

// ✅ Серверная переменная окружения
const $b24ok = B24Hook.fromWebhookUrl(process.env.BITRIX24_WEBHOOK_URL!)

// ❌ Никогда не вставляйте URL в клиентский код и не коммитьте его в Git
const $b24bad = B24Hook.fromWebhookUrl(
  'https://company.bitrix24.com/rest/1/abcdef123456/'
)

FAQ