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.
Actualizado el . 5 min de lectura
Incluido en todos los planes. Ver precios
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
0 s
Intento 1
Espera de 5 s hasta el siguiente.
5 s
Intento 2
Espera de 10 s hasta el siguiente.
15 s
Intento 3
Espera de 20 s hasta el siguiente.
35 s
Intento 4
Espera de 40 s hasta el siguiente.
75 s
Intento 5
Si también falla, la entrega queda en FAILED_PERMANENTLY.
- 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
SUCCESSno se puede reintentar. - De la respuesta de tu servidor se guardan los primeros 5.000 caracteres, que ves en el detalle de la entrega.
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.
Estados de una entrega
Estados de una entrega
Pendiente
PENDING
Primer intento en curso.Se llega desde Pendiente cuando: 5xx, fallo de red, 408, 425 o 429
Reintentando
RETRYING
Hay otro intento programado (nextRetryAt).Se llega desde Pendiente cuando: Otro 4xx, redirección o dirección bloqueada
Fallo definitivo
FAILED_PERMANENTLY
La entrega se cierra sin éxito.Se llega desde Fallo definitivo cuando: Pasan 7 días
Descartada
DEAD_LETTER
Pasa sola a este estado 7 días después de cerrarse.
Se llega desde Pendiente cuando: Tu servidor responde 2xx
Entregado
SUCCESS
Estado final
Pasa a Entregado cuando tu servidor responde 2xx. No se puede reintentar.
Otras transiciones
- Reintentando pasa a Entregado: Un reintento recibe 2xx.
- Reintentando pasa a Fallo definitivo: Se agotan los 5 intentos o llega un error definitivo.
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.
Siguiente paso
Revisa qué trae cada aviso en Avisos: contenido y catálogo de eventos.