¿Cómo se reintentan los webhooks fallidos y los eventos llegan en orden?

Tu receptor puede almacenar un evento incluso cuando el emisor nunca recibe su confirmación. Un reintento puede, por tanto, repetir trabajo que tu aplicación ya aceptó.

Los reintentos retrasan algunos eventos. Eventos más recientes pueden llegar antes de que esos reintentos terminen. Almacena los identificadores de evento y las horas de ocurrencia para que esas entregas no sobrescriban trabajo más reciente.

¿Qué cuenta como una entrega fallida?

Bird considera una entrega como fallida cuando recibe una respuesta sin éxito o la solicitud expira.

Devuelve HTTP 2xx después de almacenar el evento para detener los reintentos de esa entrega. Una redirección, error de cliente o error de servidor sigue siendo elegible para reintento.

Por ejemplo, 400 registra una solicitud rechazada pero no le indica a Bird que la descarte. Usa una respuesta de error cuando falle la verificación de firma o el almacenamiento durable, para que la entrega pueda recuperarse.

Almacena el evento antes de confirmarlo. Devolver éxito primero puede perder el evento si la operación de almacenamiento posterior falla.

Mantén el procesamiento lento en un worker en segundo plano para que tu receptor pueda responder rápidamente. La tarea del receptor es verificar y preservar el evento antes de que ese trabajo comience.

¿Cuál es el calendario de reintentos?

Bird usa siete intervalos de reintento después del intento inicial, para un total de ocho intentos.

El calendario te da aproximadamente 27,5 horas para reparar un receptor antes de que terminen los intentos automáticos.

Bird ajusta aleatoriamente cada espera hasta un 20 por ciento en cualquier dirección para distribuir los reintentos tras una caída. Una espera de cinco minutos, por tanto, varía entre cuatro y seis minutos antes de otros ajustes.

Una respuesta de limitación de solicitudes o un timeout pueden modificar la siguiente espera. Bird también considera Retry-After, un encabezado de respuesta que solicita un retraso antes de otro intento. Trata el calendario como una ventana de recuperación en lugar de un plazo exacto.

Cada reintento conserva el webhook-id del evento, para que tu receptor pueda reconocer duplicados.

¿Qué ocurre después del último reintento?

Los reintentos automáticos se detienen para esa entrega. Puedes solicitar la reproducción de las entregas que fallaron.

Solicita la reentrega con createWebhookReplay, o desde la página del panel del endpoint. La reproducción lee el registro de intentos de entrega y selecciona los eventos que fallaron allí. Un evento Bird nunca intentado, como uno que llegó mientras el endpoint estaba pausado, no tiene intento que seleccionar, así que la reproducción no puede recuperarlo.

La respuesta es 202, lo que significa que la reproducción se pone en cola para ejecución en segundo plano. No incluye un conteo ni un identificador de tarea. Usa listWebhookAttempts para inspeccionar los intentos posteriores.

Cada reenvío consume un solo intento en lugar del calendario anterior. Bird registra el intento y da el trabajo por terminado independientemente de que tu receptor lo haya aceptado. Reenviar a un receptor que sigue roto cuesta una solicitud por evento en lugar de ocho. Repara el receptor y vuelve a solicitar el reenvío. Esos fallos no afectan el estado del endpoint. Un reenvío aceptado elimina la degradación.

La reproducción omite las entregas ya confirmadas con éxito. Una reentrega conserva su webhook-id original, así que tu manejo de duplicados sigue aplicándose.

Establece since y until como cadenas de fecha y hora para delimitar la ventana de recuperación. Ambos límites son inclusivos. Ambos se comparan con la hora del intento de entrega, no con la hora en que ocurrió el evento. Si omites since, la ventana comienza 24 horas antes de la solicitud, así que una interrupción anterior necesita una hora de inicio explícita. Si omites until, la ventana termina en el momento de la solicitud.

Los intentos se conservan durante tres días, que es el límite de alcance del reenvío. Un since anterior amplía la ventana sin recuperar nada más antiguo. Un solo reenvío cubre como máximo los 10.000 eventos más antiguos de la ventana, así que una interrupción prolongada requiere varias ventanas más estrechas.

Una organización puede solicitar 20 reproducciones por día UTC. Una solicitud adicional recibe 429 con WebhookReplayQuotaExceeded, así que combina la recuperación en una ventana en vez de solicitar una reproducción por evento.

¿Qué pasa si mi endpoint sigue fallando?

Bird marca un endpoint que falla como degradado. Pausa la entrega después de aproximadamente cinco días de fallos ininterrumpidos.

Puedes leer su status como active, degraded o paused. Un endpoint degradado sigue recibiendo entregas y reintentos. Una entrega exitosa elimina la degradación y reinicia el reloj de fallos continuos.

Un endpoint pausado deja de recibir eventos y no se reanuda automáticamente. Reactívalo con updateWebhook, estableciendo status en active. Luego reproduce la ventana, lo que recupera las entregas que fallaron antes de la pausa. Reactívalo primero: una reproducción solicitada mientras el endpoint sigue pausado devuelve 202 y no reentrega nada. Los valores de estado editables son active y paused.

Cambiar la url de recepción o completar una entrega de prueba exitosa también elimina la degradación. La URL de reemplazo debe ser accesible públicamente HTTPS, así que las direcciones privadas no pueden reparar la accesibilidad. Las URL de más de 2048 caracteres fallan la validación, así que acorta una URL generada antes de enviarla.

Editar la descripción del endpoint o las suscripciones a eventos no demuestra que pueda recibir solicitudes. Esos cambios dejan la degradación vigente, igual que una entrega de prueba fallida.

Bird envía un correo a los propietarios de la organización cuando un endpoint pasa a degradado. No envía otro correo de degradación hasta que el endpoint se recupera. Los fallos repetidos, por tanto, no producen un correo por cada intento. Un fallo después de la recuperación inicia otro período de degradación.

¿Existe una cola de mensajes no entregados?

Bird no proporciona una cola separada de eventos fallidos para que la leas. En su lugar, inspecciona los intentos de entrega y solicita la reproducción.

Repara el receptor, reactívalo si es necesario y reproduce la ventana afectada. No hay una cola separada que vaciar después.

¿Llegan los eventos en orden?

Los eventos pueden llegar en un orden distinto al orden en que ocurrieron.

Un evento email.delivered puede llegar antes que el evento email.accepted del mismo mensaje. Compara las horas del evento en timestamp antes de aplicar un cambio que sobrescribiría un estado más reciente.

Registra cada parte de un cargo SMS por separado. Por ejemplo, el cargo de entrega y una tarifa del operador son componentes de coste independientes.

El objeto cost es null hasta que un componente haya sido tasado. Los valores de sus componentes son cadenas decimales o null. El campo amount es una cadena decimal que suma los componentes presentes en ese payload.

Combina cada componente usando la marca de tiempo del evento más reciente. Reemplazar el objeto completo puede borrar un componente proporcionado por otro evento o restaurar un cargo anterior.

Un componente null significa que no fue tasado en ese payload. No significa un cargo de cero. Eventos SMS describe esa combinación en contexto, y webhooks cubre la semántica de entrega.