---
title: "Outbound webhook handler"
description: "Express server that receives Bitrix24 outbound events, fetches details via REST, dispatches by event name. Always returns 200."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/examples/webhook-handler"
last_updated: "2026-06-02"
---
# Outbound webhook handler

> Express server that receives Bitrix24 outbound events, fetches details via REST, dispatches by event name. Always returns 200.

## What it does

Stands up an Express endpoint at `POST /webhook` that maps `ONCRMDEALADD`, `ONCRMDEALUPDATE`, `ONCRMDEALDELETE` events to handlers. Each handler calls `crm.item.get` to enrich the payload (Bitrix24 only ships the entity id) and runs your downstream logic. Provides a `GET /health` endpoint for orchestration probes.

## Stack

Node.js 18+, `express`.

## Install

```bash
pnpm add express
```

## Environment

```bash
export B24_HOOK='https://your.bitrix24.com/rest/1/secret'
export PORT=3001  # default
```

## Run

```bash
npx tsx 07-webhook-handler.ts
# expose locally for tests:
npx ngrok http 3001
```

## Source

[`skills/b24jssdk-recipes/examples/07-webhook-handler.ts`](https://github.com/bitrix24/b24jssdk/blob/main/skills/b24jssdk-recipes/examples/07-webhook-handler.ts).

## Notes

- Bitrix24 outbound events POST `application/x-www-form-urlencoded` — Express's `urlencoded({ extended: true })` parser flattens `data[FIELDS][ID]` to `payload.data.FIELDS.ID`.
- Always return `200` regardless of handler outcome. Non-2xx triggers Bitrix24 retries for up to 24 hours.
- Event registration is a one-off setup — see [recipe 11 (Outbound event registration)](https://bitrix24.github.io/b24jssdk/raw/docs/examples/event-registration.md) for `event.bind` / `event.unbind` from the SDK.
- **Verify the request origin in production.** Set `B24_APPLICATION_TOKEN` to the value from the Bitrix24 dev console (Local Application → application_token); the recipe checks `payload.auth?.application_token` against it and silently drops requests that don't match. Without this guard, anyone who knows your URL can replay arbitrary events.

## Sitemap

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