Entrega y reintentos
Qué se considera una entrega correcta, cuánto tiempo espera BreezeAuth a tu endpoint y cómo se reintentan las entregas fallidas.
Esta página explica qué ocurre entre el momento en que se produce un evento en tu organización y el momento en que tu endpoint confirma su recepción, incluido lo que hace BreezeAuth cuando algo sale mal.
Entrega
Cuando se produce un evento, BreezeAuth lo envía, normalmente en pocos segundos, a todos los webhooks activados de
la organización suscritos a ese tipo de evento. Cada entrega es una petición HTTP POST a la URL del webhook, con el
mensaje en el cuerpo en JSON y las cabeceras de firma.
Qué se considera un éxito
Un intento tiene éxito solo cuando tu endpoint responde con un estado 2xx (de 200 a 299) en menos de
15 segundos. Cualquier otra cosa es un fallo:
| Qué hace tu endpoint | Resultado |
|---|---|
Responde 2xx en menos de 15 segundos |
✅ Éxito. El cuerpo de la respuesta se ignora. |
Responde con una redirección (301, 302, 307, 308…) |
❌ Fallo. Las redirecciones no se siguen. Registra la URL final. |
Responde 4xx (como 400, 401, 404) |
❌ Fallo. |
Responde 5xx (como 500, 502, 503) |
❌ Fallo. |
| Tarda más de 15 segundos en responder | ❌ Fallo (tiempo de espera agotado). Puede que tu endpoint haya procesado el mensaje igualmente, así que cuenta con un duplicado. |
| No se puede contactar (error de DNS, conexión rechazada, certificado TLS no válido) | ❌ Fallo. |
Importante: las respuestas 3xx se tratan como errores. Una causa habitual es registrar http:// cuando el
servidor redirige a https://, u omitir una barra final que el servidor exige. Usa la URL final exacta.
Reintentos
Cuando un intento falla, BreezeAuth lo vuelve a intentar. Cada evento tiene hasta 3 intentos por webhook: la entrega original más 2 reintentos.
| Intento | Cuándo se produce |
|---|---|
| 1 | Justo después de que se produzca el evento. |
| 2 | Unos 5 segundos después de que falle el intento 1. |
| 3 | Unos 30 segundos después de que falle el intento 2. |
Si el tercer intento también falla, BreezeAuth deja de intentar entregar ese evento a ese webhook. Contando el tiempo de espera de 15 segundos de cada intento, todos se producen en aproximadamente un minuto y medio desde el evento.
Todos los intentos llevan exactamente el mismo mensaje: el mismo webhook-id, el mismo webhook-timestamp y el mismo
cuerpo. Eso es lo que permite a tu endpoint reconocer los duplicados.
Nota: el margen de reintentos es corto a propósito. Los webhooks sirven para avisarte rápidamente de los cambios, no para acumular mensajes para un endpoint caído. Si tu endpoint puede estar sin servicio durante más tiempo, añade una reconciliación periódica a través de la API.
Cambios de configuración durante los reintentos
Antes de cada intento, BreezeAuth lee la configuración actual del webhook:
- si el webhook se ha desactivado, o el tipo de evento se ha quitado de sus suscripciones, se cancelan los intentos restantes;
- si la URL ha cambiado, el siguiente intento va a la nueva URL.
Garantías de entrega
- Al menos una vez. BreezeAuth hace todo lo posible por entregar cada evento y, en algunas situaciones, puede entregar el mismo evento más de una vez. Tu endpoint debe ignorar los duplicados.
- Sin garantía de orden. Los eventos se entregan de forma independiente y los reintentos añaden retrasos, así que los mensajes pueden llegar en un orden distinto al de los eventos. Lee el estado actual de la API en lugar de depender del orden.
- Un mensaje por evento. Cada mensaje describe exactamente un evento; no se agrupan.
Cuando fallan las entregas
Cada intento, con éxito o no, queda registrado en el Historial de eventos del webhook, con el estado o el error que provocó el fallo. Consulta Historial de eventos para investigar los problemas.
Última actualización: 13 de octubre de 2026