Обработчик исходящих вебхуков

Что делает

Поднимает Express-endpoint на POST /webhook, который сопоставляет события ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMDEALDELETE обработчикам. Каждый обработчик вызывает crm.item.get, чтобы обогатить payload (Bitrix24 присылает только id сущности), и выполняет вашу логику. Предоставляет endpoint GET /health для проб оркестрации.

Стек

Node.js 18+, express.

Установка

pnpm add express

Переменные окружения

export B24_HOOK='https://your.bitrix24.com/rest/1/secret'
export PORT=3001  # по умолчанию

Запуск

npx tsx 07-webhook-handler.ts
# пробросить локально для тестов:
npx ngrok http 3001

Исходник

skills/b24jssdk-recipes/examples/07-webhook-handler.ts.

Примечания

• Исходящие события Bitrix24 шлют POST application/x-www-form-urlencoded — парсер Express urlencoded({ extended: true }) разворачивает data[FIELDS][ID] в payload.data.FIELDS.ID.
• Всегда возвращайте 200 независимо от исхода обработчика. Не-2xx запускает повторы Bitrix24 на срок до 24 часов.
• Регистрация событий — разовая настройка; про event.bind / event.unbind из SDK см. рецепт 11 (Регистрация исходящих событий).
• Проверяйте источник запроса в production. Задайте B24_APPLICATION_TOKEN равным значению из dev-консоли Bitrix24 (Локальное приложение → application_token); рецепт сверяет с ним payload.auth?.application_token и молча отбрасывает несовпадающие запросы. Без этой защиты любой, кто знает ваш URL, может повторять произвольные события.