Webhooks

Configuración de Webhooks

Umbrella envía notificaciones de Webhook a tus sistemas externos cuando ocurren eventos de garantía. Usa los Webhooks para integrarte con tu CRM, mesa de soporte, herramientas de analíticas o servicios de backend.

---

Tipos de eventos

Eventos de pólizas

Evento	Descripción
policy.created	Póliza de garantía creada (pedido completado con garantía)
policy.activated	Póliza activada (pago confirmado)
policy.expired	La póliza llegó a su fecha de vencimiento
policy.cancelled	Póliza cancelada (reembolso o cancelación del pedido)
policy.updated	Póliza actualizada (cambio de estado o de metadatos)

Eventos de reclamos

Evento	Descripción
claim.created	Nuevo reclamo presentado
claim.updated	Cambió el estado del reclamo
claim.approved	Reclamo aprobado
claim.denied	Reclamo denegado
claim.resolved	Reclamo resuelto (reemplazo enviado o reembolso emitido)

Eventos de pedidos

Evento	Descripción
order.warranty_attached	Garantía agregada a una línea de pedido
order.warranty_removed	Garantía eliminada de un pedido
order.post_purchase_completed	Venta adicional de garantía posterior a la compra completada

Eventos de clientes

Evento	Descripción
customer.policy_assigned	Póliza asignada a un cliente
customer.claim_filed	El cliente presentó un reclamo

---

Formato de la carga útil

Todas las cargas útiles siguen esta estructura:

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

• id — ID único del evento (úsalo para eliminar duplicados)
• event — tipo de evento
• data — carga útil específica del evento con los detalles del recurso
• metadata — contexto de la organización y de la integración

---

Verificación de la firma

Todos los Webhooks incluyen un encabezado X-Umbrella-Signature (HMAC-SHA256 del cuerpo de la solicitud). Verifícalo siempre antes de procesar la solicitud. Consulta la Referencia de webhooks para ver ejemplos de código de verificación.

---

Esquema de reintentos

Las entregas fallidas (respuesta distinta de 2xx o tiempo de espera agotado) se reintentan con retroceso exponencial:

Intento	Espera
1.er reintento	30 segundos
2.º reintento	2 minutos
3.er reintento	10 minutos
4.º reintento	1 hora
5.º reintento	6 horas
Último reintento	24 horas

Tu endpoint debe responder con 200, 201 o 202 en un plazo de 30 segundos. Responde de inmediato y procesa de forma asíncrona para evitar que se agote el tiempo de espera.

---

Configurar un endpoint

1. Ve a Panel → Configuración → Webhooks
2. Haz clic en Agregar endpoint
3. Ingresa la URL HTTPS de tu endpoint y selecciona los eventos
4. Copia y guarda de forma segura el secreto de firma (solo se muestra una vez)
5. Haz una prueba con Enviar evento de prueba en la página de detalles del endpoint

---

Registros de Webhooks

La página de registros muestra el historial de entregas por endpoint: tipo de evento, estado (exitoso/fallido/reintentado), código de respuesta, tiempo de respuesta, marca de tiempo y número de intentos.

---

Relacionado

• Sincronización de productos de Shopify — Sincronización mediante Webhooks de Shopify
• Integración con Shopify — La conexión general con Shopify
• Configuración de widgets — Ajustes de visualización del widget