v1.2.0

Outbound event registration

CLI tool — list, bind, and unbind Bitrix24 outbound webhook events via event.get / event.bind / event.unbind. Pairs with the webhook handler recipe.
Source on GitHub

What it does

Recipe 7 (webhook handler) assumes events are already bound. This recipe closes that loop:

  • list — print all currently bound events on the portal
  • bind — register a target URL as a handler for ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMDEALDELETE (idempotent — re-binding the same pair is a no-op)
  • unbind — remove those bindings

Run it once after deploying your handler; re-run on every config change.

Stack

Node.js 18+. No external dependencies.

Environment

export B24_HOOK='https://your.bitrix24.com/rest/1/secret'
export HANDLER_URL='https://your-server.example.com/webhook'   # required for bind/unbind

Run

npx tsx 11-event-registration.ts list
npx tsx 11-event-registration.ts bind
npx tsx 11-event-registration.ts unbind

Source

skills/b24jssdk-recipes/examples/11-event-registration.ts.

Notes

  • event.bind returns the code ERROR_EVENT_BINDING_EXISTS if the same (event, handler) pair is already bound — the recipe treats this as success for idempotent runs.
  • event.unbind raises if the binding doesn't exist; the recipe logs and continues.
  • The webhook used to call event.bind must have the event scope (it does for incoming webhooks created from the portal admin UI).
  • For OAuth-installed apps, the equivalent of event.bind is binding events at the application level via the dev console or event.bind with the app's auth.

Error handling

Demonstrates the four error layers (SdkError / AjaxError / network / soft) and the hardErrorCodes / softErrorCodes / retryOnNetworkError knobs on the restriction manager.

OAuth install

Express server that handles ONAPPINSTALL / ONAPPUPDATE / ONAPPUNINSTALL events for a Bitrix24 marketplace app, persists tokens per portal, and builds a B24OAuth client on demand with a refresh callback wired to storage.