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 18+, 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 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) 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.