Referencia de webhooks

Los webhooks envían solicitudes HTTP POST a tu endpoint cuando ocurren eventos en Umbrella, así no necesitas consultar la API periódicamente para detectar cambios.

Configuración

1. Ve a Panel > Configuración > Integraciones > Webhooks
2. Haz clic en Agregar endpoint de Webhook
3. Ingresa la URL HTTPS de tu endpoint
4. Selecciona los eventos que quieres recibir
5. Guarda y almacena el secreto de firma (solo se muestra una vez)

Tu endpoint debe aceptar solicitudes POST, devolver un estado 2xx en menos de 30 segundos y aceptar application/json.

Tipos de eventos

Eventos de pólizas

Eventos de reclamos

Eventos de registro

Eventos de garantías

Estructura del payload

Todos los webhooks siguen este formato de envoltorio:

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

• id — ID único del evento (úsalo para eliminar duplicados)
• type — tipo de evento
• timestamp — cuándo ocurrió el evento
• data — payload específico del evento con los detalles del recurso correspondiente (póliza, reclamo, registro, etc.)

Verificación de la firma

Cada solicitud incluye un encabezado X-Umbrella-Signature con un hash HMAC-SHA256 del cuerpo de la solicitud. Verifícalo antes de procesar los eventos.

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)
  );
}

Estrategia de reintentos

Las entregas fallidas (respuesta distinta de 2xx, tiempo de espera agotado o error de conexión) se reintentan con espera exponencial:

Después de 7 intentos fallidos, la entrega se marca como fallida. Una respuesta 410 Gone desactiva el endpoint de forma permanente.

Pruebas

1. Ve a Panel > Configuración > Integraciones > Webhooks
2. Haz clic en tu endpoint y luego en Enviar evento de prueba
3. Selecciona un tipo de evento y revisa el resultado de la entrega

La página de detalle del webhook también muestra un registro de las entregas recientes con los códigos de estado y los tiempos.

Relacionado

• Autenticación — Seguridad y credenciales de la API
• API de reclamos — Endpoints para gestionar reclamos
• API de pólizas — Endpoints para gestionar pólizas