Garantías de entrega
Entrega al menos una vez y sin orden garantizado — reintentos, degradación, retención y reenvío
Al menos una vez, no exactamente una, y sin orden garantizado
Bitelio intenta entregar al menos una vez cada evento al que tu endpoint está suscrito, reintentando en caso de fallo según el calendario de abajo — pero nunca garantiza una entrega exactamente única, ni garantiza el orden.
Deduplica usando Bitelio-Idempotency-Id. Se mantiene estable en todos los reintentos de una misma entrega, así que el mismo evento puede llegar a tu endpoint más de una vez — por ejemplo, un intento que tuvo éxito pero cuya respuesta 200 se perdió por el camino — sin que tengas que procesarlo dos veces.
El orden no está garantizado. Puede haber más de una entrega a tu endpoint en curso a la vez, y una entrega que falla se reintenta más tarde con espera creciente mientras los eventos nuevos se siguen enviando — así que un evento de hace diez minutos puede llegar después de uno de ahora mismo. Serializar la entrega por endpoint — de una en una, estrictamente en orden — limitaría el rendimiento de toda la plataforma a lo que tu receptor más lento pueda absorber, así que Bitelio no lo hace. Si el orden te importa, ordena tú mismo por la marca de tiempo occurredAt de cada payload.
Reintentos
Cualquier respuesta fuera del rango 2xx cuenta como fallo — eso incluye los estados 3xx/4xx/5xx, un error de conexión, y una petición que no obtiene respuesta en 10 segundos (se trata como un timeout).
Una entrega recibe hasta 9 intentos en total (el primero más 8 reintentos), repartidos a lo largo de unas 22 horas y concentrados al principio para que un fallo breve por tu parte se recupere en segundos:
| Intento | Espera antes de él |
|---|---|
| 1 | — (inmediato) |
| 2 | 10s |
| 3 | 1 min |
| 4 | 5 min |
| 5 | 15 min |
| 6 | 1 h |
| 7 | 3 h |
| 8 | 6 h |
| 9 | 12 h |
Cada espera lleva aplicado hasta un ±20% de variación aleatoria (jitter), para que un lote de reintentos no llegue todo a tu endpoint en el mismo instante exacto. Cuando falla el intento 9, la entrega se marca como muerta y Bitelio deja de reintentarla — recibirás un correo al respecto salvo que ya se haya enviado una alerta de ese mismo endpoint en las últimas 24 horas (ver más abajo), y a partir de ahí la única forma de recibir ese evento es reenviarlo manualmente.
Degradación: cuando Bitelio deja de enviar por completo
Los intentos fallidos cuentan para un contador por endpoint de fallos consecutivos; cualquier entrega con éxito lo pone a cero. Tras 10 fallos consecutivos, Bitelio deja de enviar absolutamente nada a tu endpoint — no se crean nuevas entregas para él — de modo que un endpoint que claramente ha dejado de funcionar no acumule en silencio una cola cada vez mayor.
Puedes recibir dos correos de alerta distintos, y importa cuál de los dos es:
- "Webhook event dropped" — una entrega agotó sus 9 intentos y ese evento se perdió. Cuando se descartó, los eventos nuevos seguían enviándose. Eso puede cambiar momentos después: si tu endpoint cruza entonces el umbral de fallos recibirás también un correo "Webhook delivery stopped", y ese es el que describe el estado actual.
- "Webhook delivery stopped" — tu endpoint acaba de superar el umbral de 10 fallos consecutivos y se ha marcado como degradado. Bitelio ha dejado de enviarle absolutamente nada.
Para que un mismo incidente no te llene el buzón, Bitelio envía como mucho una alerta por endpoint cada 24 horas — con una excepción deliberada: "Webhook delivery stopped" se envía siempre, aunque ya haya salido un correo "Webhook event dropped" de ese mismo endpoint dentro de esa ventana. El mensaje que dice que hemos dejado de enviar nunca es el que se queda fuera. Al revés no funciona igual: una vez que se te ha avisado de que la entrega se ha detenido, los correos de eventos descartados de ese endpoint se silencian durante el resto de la ventana.
Ambos correos indican el último error y el proyecto al que pertenece el endpoint, y se envían a todos los miembros de ese proyecto. Una vez que un endpoint está degradado, Bitelio no vuelve a intentarlo por su cuenta ni comprueba si se ha recuperado — alguien tiene que ir a Ajustes → Webhooks y reactivarlo una vez esté arreglado. Reactivarlo pone el contador de fallos a cero y borra la alerta, así que un segundo incidente el mismo día recibirá su propio correo en lugar de quedar en silencio.
Retención y reenvío
El historial de entregas se conserva 30 días, tras los cuales se elimina la fila de la entrega (y su historial de intentos). El payload del evento en sí se conserva solo 7 días — pasado ese tiempo la fila sobrevive el resto de la ventana de 30 días, pero su payload ya se ha borrado.
Esa ventana de 7 días es también la ventana de reenvío: reenviar una entrega vuelve a enviar su payload guardado, así que en cuanto el payload desaparece ya no queda nada que enviar — intentar reenviarla devuelve un error.
Un reenvío no es un reintento: recibe un Bitelio-Idempotency-Id completamente nuevo, distinto del de la entrega original. Es deliberado. Un reintento reutiliza el id precisamente para que lo dedupliques; un reenvío es un reenvío deliberado que Bitelio espera que proceses de verdad — normalmente porque arreglaste un fallo en tu receptor y estás volviendo a pedir eventos que antes rechazó o nunca llegó a recibir. Si los reenvíos llevaran el id original, tu lógica de deduplicación los descartaría todos en silencio.
Un backlog extremo se gestiona aparte de la degradación
Si un endpoint acumula un backlog extremadamente grande de eventos sin entregar — por ejemplo, caído durante días — Bitelio deja de encolar nuevas entregas para él por completo, para proteger al resto de la plataforma; esos eventos se registran como omitidos en lugar de intentados. Esto exige un fallo mucho más sostenido que los 10 fallos consecutivos de la degradación anterior, pero la conclusión práctica es la misma en ambos casos: un endpoint que queda roto el tiempo suficiente acaba perdiendo eventos, así que conviene actuar cuanto antes ante un correo de degradación.