---
title: "B24Hook Class"
description: "Server-side entry point for talking to the Bitrix24 REST API through an inbound webhook (permanent token)."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api/hook"
last_updated: "2026-06-02"
---
# B24Hook Class

> Server-side entry point for talking to the Bitrix24 REST API through an inbound webhook (permanent token).

> [!CAUTION]
> The `B24Hook` object is intended **exclusively for use on the server**.
> - A webhook URL contains a secret access key. **It must never appear in client-side code (browser, mobile app)**.
> - For the client side, use [`B24Frame`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/frame.md).
> - The HTTP client is created with a client-side warning enabled by default — see [`offClientSideWarning`](#offclientsidewarning).

## 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`](https://github.com/bitrix24/b24jssdk/blob/main/packages/jssdk/src/types/b24.ts), 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.

```ts
import { B24Hook } from '@bitrix24/b24jssdk'

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

#### Method Signature

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

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes | Full webhook URL. Both URL formats are supported: `/rest//` (REST v2) and `/rest/api//` (REST v3). |
| `options.restrictionParams` | `PartialRestrictionParams>` | No | Override of the default rate-limit / operating-limit / adaptive-delay configuration. See Limiters . |

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

```ts
import { B24Hook } from '@bitrix24/b24jssdk'

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

#### Constructor Signature

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

#### `B24HookParams` Fields

| Field | Type | Description |
| --- | --- | --- |
| `b24Url` | `string` | Bitrix24 portal URL (`https://your_domain.bitrix24.com` ). |
| `userId` | `number` | Identifier of the user the webhook belongs to. |
| `secret` | `string` | Webhook secret token. |

## Quick Example

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

```ts-type
get auth(): AuthActions
```

Returns the [`AuthHookManager`](https://github.com/bitrix24/b24jssdk/blob/main/packages/jssdk/src/hook/auth.ts) instance, which implements [`AuthActions`](https://github.com/bitrix24/b24jssdk/blob/main/packages/jssdk/src/types/auth.ts):

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

```ts-type
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`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/call-rest-api-ver2.md) / [`CallV3.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/call-rest-api-ver3.md)
- [`CallListV2.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/call-list-rest-api-ver2.md) / [`CallListV3.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/call-list-rest-api-ver3.md)
- [`FetchListV2.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/fetch-list-rest-api-ver2.md) / [`FetchListV3.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/fetch-list-rest-api-ver3.md)
- [`BatchV2.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/batch-rest-api-ver2.md) / [`BatchV3.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/batch-rest-api-ver3.md)
- [`BatchByChunkV2.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/batch-by-chunk-rest-api-ver2.md) / [`BatchByChunkV3.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/batch-by-chunk-rest-api-ver3.md)
- [`tools.healthCheck.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/tools-health-check.md), [`tools.ping.make`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/tools-ping.md)

## Methods

### `getTargetOrigin`

```ts-type
getTargetOrigin(): string
```

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

### `getTargetOriginWithPath`

```ts-type
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`

```ts-type
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`

```ts-type
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](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/core-http.md).

### `setRestrictionManagerParams`

```ts-type
setRestrictionManagerParams(params: RestrictionParams): Promise<void>
```

Replaces the rate-limit / operating-limit / adaptive-delay configuration on both v2 and v3 clients at once. See [Limiters](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/limiters.md).

### `getLogger` / `setLogger`

```ts-type
getLogger(): LoggerInterface
setLogger(logger: LoggerInterface): void
```

Get or replace the logger used by the SDK and propagated into the HTTP clients. See [Logger](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/logger.md).

### `destroy`

```ts-type
destroy(): void
```

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

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

## Storing the Webhook Secret

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

```ts
// ✅ 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

**Q: Where do I get the webhook URL?**

Bitrix24 → Settings → Developers → Webhooks → Inbound webhook. See the [official documentation](https://apidocs.bitrix24.com/local-integrations/local-webhooks.html#vhodyashij-vebhuk).

**Q: Can one B24Hook instance serve the whole server?**

Yes. Create the instance once at startup and share it across requests — the HTTP clients reuse the underlying axios instance and the limiter state.

**Q: Why does fromWebhookUrl throw 'Webhook requires HTTPS protocol'?**

The factory rejects `http://` URLs by design. Webhook secrets must travel over TLS.

**Q: What does 'Access denied' mean?**

The webhook user lacks permissions for the called REST method, or the webhook itself was revoked. Recreate the webhook with the required scopes.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.