Gestión de Webhooks

Los webhooks permiten a Auris notificar a tus sistemas externos cuando ocurren eventos de autenticación — como la creación de usuarios, el inicio de sesión, los cambios de contraseña, las asignaciones de roles y más. En lugar de hacer polling a la API de Auris para detectar cambios, tu servidor recibe notificaciones HTTP POST en tiempo real con los detalles del evento.

Accede a la gestión de webhooks en Consola → Configuración → Webhooks.

Resumen de Webhooks

La página de Webhooks muestra todos los endpoints de webhook configurados para tu tenant:

Crear un Webhook

Secreto del Webhook

Cada webhook recibe un secreto de firma al crearse. Este secreto se usa para generar firmas HMAC-SHA256 para cada entrega, permitiendo a tu servidor verificar que los webhooks entrantes provienen genuinamente de Auris.

Ver el Secreto

El secreto de firma se muestra una vez inmediatamente después de la creación del webhook en un diálogo de confirmación. Lleva el prefijo whsec_ para una fácil identificación:

whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Copia el secreto y guárdalo de forma segura en las variables de entorno de tu aplicación. El secreto no se vuelve a mostrar después de que cierras el diálogo.

Verificar Firmas de Webhook

Cada entrega de webhook incluye dos cabeceras para la verificación de firmas:

Pasos de verificación en tu servidor:

1. Lee la cabecera X-Webhook-Timestamp
2. Verifica que la marca de tiempo está dentro de una ventana aceptable (por ejemplo, 5 minutos) para prevenir ataques de repetición
3. Calcula HMAC-SHA256(timestamp + "." + requestBody, webhookSecret)
4. Compara la firma calculada con la cabecera X-Webhook-Signature

Ejemplo de verificación en Node.js:

import { createHmac, timingSafeEqual } from 'crypto'
 
function verifyWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Comprueba la vigencia de la marca de tiempo (ventana de 5 minutos)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false // Demasiado antiguo o demasiado adelantado
  }
 
  // Calcula la firma esperada
  const payload = `${timestamp}.${body}`
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
 
  // Comparación en tiempo constante para prevenir ataques de temporización
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Probar Webhooks

Antes de desplegar en producción, verifica que tu endpoint recibe y procesa correctamente los payloads de webhook.

Enviar Evento de Prueba

En la página de detalles del webhook, haz clic en el botón Probar. Auris envía un evento de prueba a la URL configurada con un payload de ejemplo:

{
  "event": "webhook.test",
  "timestamp": "2025-02-10T08:15:00Z",
  "data": {
    "message": "Esta es una entrega de webhook de prueba de Auris."
  }
}

La entrega de prueba aparece en el log de Entregas, para que puedas verificar el código de estado de respuesta y ver cualquier mensaje de error.

Usar Herramientas de Prueba de Webhooks

Para el desarrollo, puedes usar un servicio de prueba de webhooks como webhook.site  o ngrok  para recibir e inspeccionar los payloads de webhook:

1. Crea una URL temporal usando tu herramienta de prueba
2. Establece esa URL como el endpoint del webhook en la Consola
3. Activa eventos (por ejemplo, crea un usuario de prueba)
4. Inspecciona el payload recibido en la herramienta de prueba
5. Actualiza la URL del webhook a tu endpoint de producción cuando estés listo

Ver Entregas

Cada endpoint de webhook tiene un log de entregas que muestra cada evento enviado a él.

Accede al log de entregas haciendo clic en cualquier webhook de la lista para abrir la página de detalles, luego desplázate a la sección Entregas.

Estados de Entrega

Haz clic en cualquier fila de entrega para ver los detalles completos:

• Payload de solicitud: El cuerpo JSON enviado a tu endpoint
• Cuerpo de respuesta: La respuesta devuelta por tu endpoint (primeros 1 KB)
• Cabeceras de respuesta: Cabeceras HTTP devueltas
• Mensaje de error: Si la entrega falló, el error específico

Reintentar Entregas Fallidas

Auris reintenta automáticamente las entregas fallidas (5xx, tiempo de espera, errores de red) con retroceso exponencial:

Después de 3 intentos fallidos, la entrega se marca como fallida y no se producen más reintentos automáticos.

Reintento Manual

Para reintentar manualmente una entrega fallida:

1. Abre la página de detalles del webhook
2. Encuentra la entrega fallida en el log
3. Haz clic en el botón Reintentar en esa fila de entrega

El reintento manual envía exactamente el mismo payload a la URL actual del webhook. Si has cambiado la URL desde la entrega original, el reintento va a la nueva URL.

Rotar Secretos

Si sospechas que un secreto de webhook ha sido comprometido, o si necesitas rotar secretos como parte de una política de seguridad, puedes generar un nuevo secreto:

Importante: La rotación es inmediata. En cuanto rotas, el secreto anterior es inválido y todas las entregas posteriores se firman con el nuevo secreto. Si tu endpoint todavía está configurado con el secreto antiguo, rechazará las entregas hasta que lo actualices. Planifica una breve ventana de entregas fallidas durante la rotación.

Para minimizar las interrupciones:

1. Actualiza el código de tu endpoint para aceptar firmas del secreto antiguo o nuevo
2. Rota el secreto en la Consola
3. Después de confirmar que las entregas tienen éxito con el nuevo secreto, elimina el secreto antiguo del código de tu endpoint

Habilitar y Deshabilitar Webhooks

Cada webhook tiene un interruptor Activo en su página de detalles. Cuando está deshabilitado:

• No se entregan eventos al endpoint
• La configuración del webhook se preserva (URL, eventos, secreto)
• No aparecen entregas en el log mientras está deshabilitado
• Al volver a habilitar, se reanudan las entregas para nuevos eventos (los eventos que ocurrieron mientras estaba deshabilitado no se reproducen)

Usa esto para pausar temporalmente las entregas durante el mantenimiento del endpoint sin perder la configuración del webhook.

Resumen de Categorías de Eventos

Auris admite más de 50 tipos de eventos de webhook, organizados en las siguientes categorías:

Cada payload de evento sigue una estructura consistente:

{
  "event": "user.created",
  "timestamp": "2025-02-10T08:15:00Z",
  "tenantId": "acme-corp",
  "data": {
    // Payload específico del evento
  }
}

El campo data varía según el tipo de evento y contiene los datos de la entidad relevante en el momento del evento.

Guías Relacionadas

• Integración de Webhooks — Guía para Desarrolladores — Construir un consumidor de webhooks con verificación de firmas
• Motor de Acciones — Alternativa para la lógica dentro del flujo (se ejecuta durante la autenticación, no después)
• Registros de Auditoría — Ver todos los eventos de autenticación con pistas de auditoría completas