Справочник по Webhook

Webhook отправляют HTTP-запросы POST на ваш эндпоинт, когда в Umbrella происходят события, поэтому вам не нужно периодически опрашивать API в поисках изменений.

Настройка

1. Откройте Панель управления > Настройки > Интеграции > Webhook
2. Нажмите Добавить эндпоинт Webhook
3. Введите URL вашего эндпоинта HTTPS
4. Выберите события, которые хотите получать
5. Сохраните и надёжно сохраните секрет подписи (он показывается только один раз)

Ваш эндпоинт должен принимать запросы POST, возвращать статус 2xx в течение 30 секунд и принимать application/json.

Типы событий

События полисов

События заявок

События регистрации

События гарантий

Структура данных

Каждый Webhook использует такую обёртку:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

• id — уникальный ID события (используйте для дедупликации)
• type — тип события
• timestamp — когда произошло событие
• data — данные конкретного события со сведениями о соответствующем ресурсе (полис, заявка, регистрация и т. д.)

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

Каждый запрос содержит заголовок X-Umbrella-Signature с хешем HMAC-SHA256 тела запроса. Проверяйте его перед обработкой событий.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Повторные попытки

Неудачные доставки (статус не 2xx, тайм-аут, ошибка соединения) повторяются с экспоненциальной задержкой:

После 7 неудачных попыток доставка помечается как неудачная. Ответ 410 Gone навсегда отключает эндпоинт.

Тестирование

1. Откройте Панель управления > Настройки > Интеграции > Webhook
2. Выберите свой эндпоинт и нажмите Отправить тестовое событие
3. Выберите тип события и проверьте результат доставки

На странице Webhook также отображается журнал последних доставок с кодами статуса и временем.

Связанные материалы

• Аутентификация — безопасность API и учётные данные
• API заявок — эндпоинты для управления заявками
• API полисов — эндпоинты для управления полисами