Webhooks

Webhooks уведомляют ваше приложение о событиях платформы: новый контакт, изменение сделки, оплата заказа и другие.

Подписка

Манифест приложения:

{
  "webhookUrl": "https://your-app.example.com/hooks",
  "webhookSecret": "your-secret-at-least-16-chars"
}

Требования:

• webhookUrl — только HTTPS;
• webhookSecret — минимум 16 символов, используется для подписи HMAC;
• подписка оформляется через API или в Developer Portal.

Формат события

POST <webhookUrl> с заголовками:

Заголовок	Значение
X-Maxscrm-Event	тип события, например contact.created
X-Maxscrm-Signature	HMAC-SHA256 подпись тела
X-Maxscrm-Delivery	номер попытки доставки

{
  "event": "contact.created",
  "orgId": "org-123",
  "timestamp": "2026-08-24T12:00:00Z",
  "data": { "id": "contact-456", "name": "Иван Петров" }
}

Проверка подписи

import crypto from 'node:crypto';

const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  // подпись верна — обрабатываем
}

Ретраи

• при ошибке (5xx, таймаут) доставка повторяется с экспоненциальной задержкой;
• максимальное число попыток — 5;
• после исчерпания попыток событие помечается как недоставленное (видно в журнале вебхуков).

Рекомендации

• отвечайте 200 быстро, тяжёлую обработку выносите в очередь;
• идемпотентность: храните X-Maxscrm-Delivery/event.id, чтобы не обрабатывать дубликаты;
• не блокируйте обработку на внешних вызовах.