Outbound webhook handler

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 20+, express.

Install

pnpm add express

Environment

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

Run

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

Source

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 2xx first, then verify and process. Bitrix24 has no automatic retry (a failed/slow delivery is dropped, and slow handlers get deprioritized), so reply fast — see Security patterns.
• Event registration is a one-off setup — see recipe 11 (Outbound event registration) 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.