Introducción a los webhooks

Un webhook es un mensaje que BreezeAuth envía a uno de tus sistemas en cuanto algo cambia en tu organización. Por ejemplo, BreezeAuth puede avisar a tu sistema en el momento en que un usuario se une, un grupo gana un miembro o se elimina una aplicación.

Sin webhooks, tus sistemas tendrían que preguntar a BreezeAuth “¿ha cambiado algo?” cada pocos minutos. Con webhooks, BreezeAuth se lo dice, al instante.

Para qué usar los webhooks

• Aprovisionar y desaprovisionar cuentas. Crear una cuenta en un sistema interno cuando alguien se une a la organización, y desactivarla en cuanto se elimina su membresía.
• Mantener los accesos sincronizados. Replicar los miembros de los grupos o las asignaciones de aplicaciones en otra herramienta, como una plataforma de RR. HH., un CRM o un data warehouse.
• Avisar a tu equipo. Notificar al equipo de seguridad o de TI cuando se añade un dominio o cambia la configuración de una aplicación.
• Alimentar tu propio registro de auditoría. Guardar los cambios de identidad en tu sistema de registros o de cumplimiento normativo.

Cómo funciona

1. Algo cambiaSe crea, actualiza o elimina un usuario, grupo, aplicación, asignación o dominio.
2. BreezeAuth firma un mensajeEl mensaje indica qué ha ocurrido y va firmado para que puedas demostrar que viene de BreezeAuth.
3. Tu endpoint lo recibeBreezeAuth envía una petición POST a la URL que has registrado.
4. Confirmas la recepciónTu endpoint responde con un estado 2xx en menos de 15 segundos. Si no, BreezeAuth lo vuelve a intentar.

Para empezar a recibir eventos, alguien con permiso para gestionar webhooks registra un endpoint: una URL de tu lado, junto con la lista de eventos que debe recibir. Puedes registrar varios webhooks, por ejemplo uno por sistema, cada uno con su propia selección de eventos. Consulta Crear y gestionar webhooks.

Qué contiene un mensaje

Cada mensaje describe un evento y solo incluye los identificadores de lo que ha cambiado, no todos los detalles. Por ejemplo, cuando se crea un usuario, el mensaje te da el identificador de la nueva membresía, pero no el nombre ni el correo de la persona. Después, tu sistema usa la API de BreezeAuth para obtener los detalles actuales que necesite.

{
  "uuid": "6c1f0f8e-4f5b-4a53-9d0e-2b7c9a1e3f42",
  "organizationsUuid": "0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d",
  "timestamp": "2026-10-13T14:32:05.123Z",
  "type": "membership.created",
  "data": {
    "membershipsUuid": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

Este formato mantiene los datos personales fuera de los mensajes y garantiza que tu sistema trabaje siempre con información actualizada, aunque los mensajes lleguen tarde o desordenados. La lista completa de eventos está en el catálogo de eventos.

Resumen rápido

Tema	Comportamiento
Estándar	Sigue la especificación Standard Webhooks, con firmas asimétricas.
Transporte	HTTP POST con cuerpo JSON (Content-Type: application/json).
Firma	Ed25519, enviada en la cabecera webhook-signature. La clave usada se identifica con la cabecera webhook-keyid.
IP de origen	Un conjunto fijo y publicado de direcciones, que puedes permitir en tu cortafuegos.
Éxito	Solo respuestas 2xx. Las redirecciones (3xx) no se siguen y cuentan como fallo.
Tiempo de espera	15 segundos por intento.
Intentos	Hasta 3 por evento: la entrega original más 2 reintentos, tras unos 5 y 30 segundos.
Garantía de entrega	Al menos una vez. El mismo mensaje puede llegar más de una vez, así que tu endpoint debe ignorar los duplicados.
Orden	No garantizado. Usa la API para leer el estado actual en lugar de depender del orden de los mensajes.
Supervisión	Cada intento queda registrado en el Historial de eventos del webhook, en la consola de administración.

Responsabilidades del sistema receptor

Los webhooks solo son seguros y fiables si el sistema que los recibe sigue unas pocas reglas. Tus desarrolladores encontrarán los detalles en las páginas siguientes; en resumen, el receptor debe:

Recibir eventos de forma fiable explica cada regla con ejemplos.

Para añadir una capa extra de protección, también puedes restringir tu endpoint para que solo acepte peticiones de las direcciones IP de BreezeAuth.

Próximos pasos

• Crea y gestiona webhooks en la consola de administración.
• Consulta el catálogo de eventos para elegir los eventos que necesitas.
• Comparte Verificar firmas y Recibir eventos de forma fiable con los desarrolladores que vayan a construir tu endpoint.