# Entregas y reintentos de los avisos Cuántas veces se reintenta un aviso, qué respuestas cierran la entrega, qué estados recorre y dónde se consultan y se reintentan las entregas. Esta página explica qué pasa con cada aviso desde que sale de UTILIA OS hasta que tu servidor lo acepta (o se da por perdido), y cómo consultar y reintentar las entregas. ## Política de reintentos Cada aviso se intenta entregar hasta **5 veces**: el primer intento y 4 reintentos, con esperas que se duplican entre uno y otro. **Reintentos de un aviso que no llega** 1. **0 s**: Intento 1. Espera 5 s hasta el siguiente. 2. **5 s**: Intento 2. Espera 10 s hasta el siguiente. 3. **15 s**: Intento 3. Espera 20 s hasta el siguiente. 4. **35 s**: Intento 4. Espera 40 s hasta el siguiente. 5. **75 s**: Intento 5. Si también falla, la entrega queda en FAILED_PERMANENTLY. _Las horas suponen que cada intento falla al momento; a cada una se suma lo que tarde tu servidor, hasta 30 segundos._ - Un aviso está entregado cuando tu servidor responde **2xx**. UTILIA OS espera la respuesta como mucho **30 segundos**. - Los errores **5xx y los fallos de red sí se reintentan**. - Los errores **4xx son definitivos y cierran la entrega en el primer fallo**, sin gastar los reintentos que quedan. Las tres excepciones, que sí se reintentan, son **408**, **425** y **429**. - Mientras dura la transición de una clave de firma renovada, un **400, 401 o 403** no cierra la entrega todavía: UTILIA OS la reenvía en el acto, una sola vez, firmada con la otra clave (el mismo cuerpo y la misma marca de tiempo). Si ese reenvío también falla, cuenta su respuesta. - Una **redirección (3xx)** también es definitiva: UTILIA OS no la sigue. Configura la dirección final. - Todos los intentos de un mismo aviso llevan el mismo `X-Utilia-Delivery-Id`, así que tu servidor puede descartar duplicados por esa clave. - El reintento manual desde el panel vuelve a encolar la entrega con **3 intentos** y las mismas esperas. Una entrega en `SUCCESS` no se puede reintentar. - De la respuesta de tu servidor se guardan los primeros **5.000 caracteres**, que ves en el detalle de la entrega. > **Atención: Un 401 por firma inválida no se reintenta** > > Si tu servidor rechaza el aviso por firma inválida (`401`) o con cualquier otro > 4xx distinto de 408, 425 y 429, la entrega queda en `FAILED_PERMANENTLY` en el > primer intento y no vuelve a intentarse sola. La única salvedad es el reenvío con > la otra clave durante la renovación de la clave de firma. Corrige la comprobación y > reinténtala a mano desde el historial de entregas, en la pestaña > **Avisos a tu servidor** de la ficha de la aplicación. ### El aviso de prueba El botón **Probar** de **Configuración › Avisos a tu servidor** firma la petición con el **mismo código** que una entrega real: la misma cadena firmada, las mismas claves de firma y las mismas cabeceras `X-Utilia-*`. Si tu servidor la acepta, aceptará también las reales. La prueba no sale si los avisos están desactivados o si la clave de firma no se puede recuperar, y te dice el motivo, porque en esos casos tampoco saldría una entrega real. Lo que la prueba no hace: **no queda en el historial de entregas** y **no se reintenta**. Para comprobar el recorrido completo, con reintentos incluidos, provoca un evento real y búscalo en el historial. La prueba espera la respuesta de tu servidor como mucho **10 segundos**, y la entrega real, 30. Si tu servidor tarda entre 10 y 30 segundos, la prueba falla aunque los avisos reales sí le lleguen: responde antes y haz el trabajo largo después. La comprobación del receptor (`POST /api/external/v1/diagnostics/webhook-receiver-check`, con la clave de la aplicación) espera, en cambio, 30 segundos por aviso, como la entrega real. Para recibir un evento concreto del catálogo, la pestaña **Pruebas** de la aplicación y `POST /api/external/v1/diagnostics/webhook-sample` envían una **muestra** de ese evento: firmada igual, con `livemode: false` y `meta.test: true`. Las de los eventos de facturación (`INVOICE_*`), de métodos de pago (`PAYMENT_METHOD_ADDED` y `PAYMENT_METHOD_REMOVED`) y de salud de la aplicación (`APP_HEALTH_CHANGED`) tienen la forma de los avisos reales, campo por campo; las demás son genéricas. Ver [Probar los avisos a tu servidor](https://os.utilia.ai/docs/developers/getting-started/webhook-testing). ## Estados de una entrega **Estados de una entrega** 1. **Pendiente** (`PENDING`). Primer intento en curso. - **Reintentando** (`RETRYING`). Se llega desde Pendiente cuando: 5xx, fallo de red, 408, 425 o 429. Hay otro intento programado (nextRetryAt). - **Fallo definitivo** (`FAILED_PERMANENTLY`). Se llega desde Pendiente cuando: Otro 4xx, redirección o dirección bloqueada. La entrega se cierra sin éxito. - **Descartada** (`DEAD_LETTER`). Se llega desde Fallo definitivo cuando: Pasan 7 días. Pasa sola a este estado 7 días después de cerrarse. 2. **Entregado** (`SUCCESS`, estado final). Se llega desde Pendiente cuando: Tu servidor responde 2xx. Pasa a Entregado cuando tu servidor responde 2xx. No se puede reintentar. Otras transiciones: - Reintentando → Entregado: Un reintento recibe 2xx. - Reintentando → Fallo definitivo: Se agotan los 5 intentos o llega un error definitivo. _Una entrega en Fallo definitivo se puede reintentar a mano; en Entregado, no._ Una entrega también queda en Fallo definitivo, sin llegar a salir, si la clave de firma de la aplicación no se puede recuperar. Algunos avisos de cobros pueden aparecer un momento en `IN_FLIGHT` (petición en curso), y el filtro de estado admite además `FAILED`, `DELIVERED` y `FAILED_RETRY`, que vienen de una versión anterior. Las entregas **descartadas** (`DEAD_LETTER`) se **archivan** a los 90 días de cerrarse: dejan de aparecer en el historial, aunque el registro se conserva para auditoría. Las entregadas y las demás no se archivan. ## Consultar y reintentar entregas El historial está en la ficha de la aplicación, en **Configuración › Avisos a tu servidor**: cada entrega con su estado, sus intentos, el contenido que se envió y lo que contestó tu servidor (los primeros 5.000 caracteres). Desde el detalle de una entrega que no llegó la puedes reintentar; una que ya llegó bien, no. Para automatizarlo, la herramienta MCP `integrations` tiene `apps_webhooks_list_deliveries` (con filtros por estado y por evento), `apps_webhooks_get_delivery` y `apps_webhooks_retry_delivery`, con los permisos de la persona que autoriza el acceso. Está en la [Referencia de herramientas MCP](https://os.utilia.ai/docs/developers/mcp/reference). ## Siguiente paso Revisa qué trae cada aviso en [Avisos: contenido y catálogo de eventos](https://os.utilia.ai/docs/developers/webhooks/events).