Entregas y reintentos de los avisos
Cuántas veces se reintenta un aviso, qué respuestas cierran la entrega, qué estados recorre y cómo consultar y reintentar entregas desde la API del panel.
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.
- 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. Corrige la comprobación y
reinténtala a mano desde el histórico de entregas de
Ajustes › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta.
El aviso de prueba
El botón Probar de la pestaña Avisos a tu servidor (POST /api/integrations/apps/:id/webhook/test) firma la petición con el mismo código que una entrega real: la misma cadena firmada, la clave de firma vigente y las cinco 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.
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.
A los 90 días de cerrarse, la entrega se archiva: deja de aparecer en el historial, aunque el registro se conserva para auditoría.
Consultar y reintentar entregas desde la API del panel
El historial de entregas se ve en la pestaña Avisos a tu servidor de la ficha de la aplicación. También se puede consultar con la API del panel, que no acepta X-Api-Key: se llama con la sesión de una persona (Authorization: Bearer <token>), con el aplicativo Integraciones en el plan y el permiso «Ver aplicaciones externas» para leer o «Editar aplicaciones externas» para reintentar y probar.
/api/integrations/apps/:id/webhook-deliveriesLista las entregas de la aplicación, de la más reciente a la más antigua, con filtros por estado y por evento.
/api/integrations/apps/:id/webhook-deliveries/:deliveryIdDetalle de una entrega: contenido enviado, respuesta de tu servidor, último intento y próximo intento programado.
/api/integrations/apps/:id/webhook-deliveries/:deliveryId/retryVuelve a encolar una entrega. Responde 204 cuando queda encolada; el resultado se consulta después en su detalle.
/api/integrations/apps/:id/webhook/testEnvía un aviso de prueba firmado a la dirección guardada.
Parámetros del listado y el detalle
- statusenum
- Filtra por estado: PENDING, SUCCESS, RETRYING, FAILED_PERMANENTLY o DEAD_LETTER (admite también IN_FLIGHT, FAILED, DELIVERED y FAILED_RETRY).
- eventstring
- Filtra por evento, por ejemplo INVOICE_PAID.
- pagenumber
- Página del listado. Por defecto 1.
- limitnumber
- Entregas por página. Por defecto 20, máximo 100.
- deliveryIdstringobligatorio
- Identificador de la entrega, para el detalle o el reintento.
Respuesta
El listado devuelve deliveries y pagination. Cada entrega del listado trae
sus datos de resumen; lastAttemptAt, nextRetryAt, payload y
responseBody solo vienen en el detalle de una entrega.
- deliveriesarrayobligatorio
- Entregas de la página pedida.
- paginationobjectobligatorio
- page, limit, total y totalPages.
- attemptCountnumberobligatorio
- Intentos hechos hasta ahora.
- statusenumobligatorio
- Estado de la entrega en el momento de la consulta.
- nextRetryAtstring
- Próximo intento programado. Solo en el detalle; es nulo cuando la entrega ya se ha cerrado.
Ejemplo
curl -X GET 'https://os.utilia.ai/api/integrations/apps/:id/webhook-deliveries' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token JWT>'Errores comunes
- 401 por token de sesión ausente o inválido (incluye enviar
X-Api-Keyen lugar deAuthorization: Bearer). - 403 por falta de permiso («Ver aplicaciones externas» o «Editar aplicaciones
externas») o porque el plan no incluye Integraciones (
MODULE_NOT_ENABLED). - 404
DELIVERY_NOT_FOUNDsi la entrega no existe en esa aplicación. - 400
DELIVERY_ALREADY_SUCCESSal reintentar una entrega ya entregada con éxito. - 400
WEBHOOK_NO_URLoWEBHOOK_URL_INVALIDen el envío de prueba, cuando la aplicación no tiene dirección o la dirección apunta a una red privada.
Siguiente paso
Revisa qué trae cada aviso en Avisos: contenido y catálogo de eventos.