Crear y gestionar webhooks · BreezeAuth Docs

Los webhooks se configuran por organización en la consola de administración de BreezeAuth. Esta página te guía paso a paso. No hace falta programar para configurar un webhook, pero alguien de tu lado debe proporcionar la URL del endpoint: la dirección del sistema que recibirá los mensajes.

Antes de empezar

Permisos. Necesitas permiso para ver y gestionar webhooks en tu organización. Si la pestaña Webhooks aparece deshabilitada, o no ves el botón Añadir webhook, pide ayuda a un administrador de tu organización.
Una URL de endpoint. Tus desarrolladores te darán esta dirección, por ejemplo https://ejemplo.com/webhooks/breezeauth. Antes de activar el webhook en producción, el endpoint ya debería ser capaz de verificar firmas y de confirmar los mensajes rápidamente.
Cortafuegos (opcional). Si tu equipo de redes restringe el tráfico entrante, o si quieres hacerlo, permite que las direcciones IP de BreezeAuth accedan al endpoint. Las peticiones desde esas direcciones no deben bloquearse, o las entregas fallarán.

Consejo: usa una URL https://. BreezeAuth también acepta http://, pero en ese caso los mensajes viajan sin cifrar por internet.

Encontrar los webhooks de tu organización

Inicia sesión en la consola de administración.
En la barra lateral, selecciona Organización. Se abre la página Gestionar organización.
Selecciona la pestaña Webhooks.

La lista muestra todos los webhooks registrados en la organización, con su URL, su Estado (Habilitado o Deshabilitado), los Eventos suscritos y la fecha de creación. Selecciona una fila para abrir los detalles del webhook.

Crear un webhook

En la pestaña Webhooks, selecciona Añadir webhook. Se abre el formulario Nuevo webhook.
Rellena los campos que se describen a continuación.
Selecciona Crear webhook.

Campo	Descripción
Nombre	Una etiqueta para reconocer el webhook, por ejemplo “Sistema de RR. HH.” o “Eventos de facturación”. Hasta 255 caracteres. Solo lo ves tú.
URL	La dirección que recibirá los mensajes. Hasta 255 caracteres. Las redirecciones no se siguen, así que introduce la dirección final (consulta Entrega y reintentos).
Eventos	Los eventos que recibe este endpoint. Elige solo los que necesite el sistema receptor. Consulta el catálogo de eventos. Un webhook sin eventos seleccionados no recibe nada.
Activado	Si está marcado (por defecto), los eventos se envían. Desmárcalo para pausar las entregas sin perder la configuración.

A partir de ese momento, cada evento suscrito en la organización se entrega a la URL en pocos segundos.

Nota: cada webhook recibe su propia copia de cada evento al que está suscrito. Si dos webhooks apuntan a la misma URL y se suscriben al mismo evento, esa URL recibe el evento dos veces, con el mismo identificador de evento.

Editar un webhook

Abre el webhook desde la pestaña Webhooks.
Selecciona Actualizar.
Cambia el nombre, la URL, los eventos o la opción Activado y selecciona Guardar cambios.

Los cambios se aplican de inmediato, también a los reintentos que aún estén pendientes:

Si desactivas el webhook, o quitas un evento de su lista, los reintentos pendientes de ese webhook o evento se cancelan.
Si cambias la URL, los siguientes intentos van a la nueva URL.

Pausar las entregas

Para detener las entregas temporalmente, por ejemplo durante el mantenimiento del sistema receptor, edita el webhook y desmarca Activado. Los eventos que ocurren mientras el webhook está desactivado no se guardan para más tarde: simplemente no se envían. Cuando lo vuelvas a activar, solo se entregarán los eventos nuevos. Tu sistema puede recuperar lo que se haya perdido leyendo los datos actuales desde la API (consulta Recibir eventos de forma fiable).

Eliminar un webhook

Abre el webhook desde la pestaña Webhooks.
Selecciona Eliminar.
Confírmalo en el cuadro de diálogo Eliminar webhook.

Importante: eliminar un webhook no se puede deshacer. Las entregas se detienen de inmediato y el historial de eventos del webhook deja de estar disponible en la consola de administración. Si solo necesitas detener las entregas durante un tiempo, desactiva el webhook.

Comprobar lo que se ha enviado

La página de detalles de cada webhook muestra su Historial de eventos: cada intento de entrega, si tuvo éxito y, si no, por qué. Consulta Historial de eventos.

Los cambios quedan auditados

La creación, la actualización y la eliminación de webhooks quedan registradas en los Registros de auditoría de tu organización, junto con quién hizo el cambio y cuándo.