Reintentos e idempotencia
Al terminar esta página sabrás cuántas veces y con qué espaciado Neat reintenta un webhook no
confirmado, y cómo usar Idempotency-Key para que reintentar una request desde tu servidor nunca abra
un cobro duplicado.
Reintentos de webhook
Sección titulada «Reintentos de webhook»Neat espera hasta 9 segundos por una respuesta a cada entrega. Confirma la entrega con cualquier
2xx. Se reintenta con espera creciente cuando no respondes, cuando la conexión falla y cuando
respondes 408, 429 o cualquier 5xx. Cualquier otra respuesta se toma como un rechazo
definitivo: la entrega queda marcada como fallida y no se reintenta, porque un 400 o un 404 no
mejoran solos. Si tu endpoint devuelve 4xx por una caída temporal, devuelve 503 en su lugar.
La espera crece así:
| Intento | Espera hasta el siguiente |
|---|---|
| 1 | 2 minutos |
| 2 | 4 minutos |
| 3 | 8 minutos |
| 4 | 16 minutos |
| 5 | 32 minutos |
| 6 | 64 minutos |
| 7 | 128 minutos |
| 8 en adelante | 256 minutos |
Neat reintenta hasta 12 veces o durante 24 horas desde el primer intento, lo que ocurra primero. Al
agotarse, el evento queda marcado como no entregado y Neat no lo reintenta más por su cuenta; el cobro
sigue visible en GET /v1/checkout-sessions/{sessionId}. Estos tiempos describen el comportamiento
actual de la API, no un compromiso contractual.
El timestamp y la firma se renuevan en cada intento; event_id y el cuerpo permanecen iguales entre
reintentos del mismo evento.
Responde rápido, procesa después
Sección titulada «Responde rápido, procesa después»Guarda el evento por su event_id y responde 2xx de inmediato; procesa el efecto (marcar la
obligación como pagada, por ejemplo) de forma asíncrona si tu procesamiento puede tardar. Una respuesta
lenta cuenta como no confirmada a los 9 segundos y dispara un reintento, aunque tu servidor sí lo
haya recibido.
Deduplica por Neat-Event-Id
Sección titulada «Deduplica por Neat-Event-Id»La entrega es al menos una vez: el mismo evento puede llegar más de una vez, incluida una entrega
después de que ya lo procesaste. Guarda los event_id que ya procesaste y responde 2xx sin volver a
aplicar el efecto ante uno repetido.
Idempotency-Key al crear una sesión
Sección titulada «Idempotency-Key al crear una sesión»Idempotency-Key es obligatoria en POST /v1/checkout-sessions. Sin ella, la API responde
422 VALIDATION_ERROR con "field": "Idempotency-Key". Usa entre 8 y 128 caracteres ASCII
([A-Za-z0-9._:-]).
La llave identifica esa solicitud de creación, no un cobro. Si tu llamada termina en timeout o no recibes respuesta, repite exactamente la misma llave con exactamente el mismo cuerpo.
| Situación | Resultado |
|---|---|
| Llave nueva | Crea una sesión nueva (sujeto a las reglas de external_reference, ver Sesiones de checkout). |
| Misma llave, mismo cuerpo | Devuelve la misma respuesta guardada, mismo session_id, mismo checkout_url, mismo expires_at, con 201 Created otra vez, aunque esa sesión ya haya vencido. No abre una segunda sesión. |
| Misma llave, cuerpo distinto | 409 IDEMPOTENCY_CONFLICT. |
Sin cabecera Idempotency-Key, o con un formato inválido |
422 VALIDATION_ERROR, "field": "Idempotency-Key". |
La comparación de “mismo cuerpo” es sobre el contenido ya validado del request, no sobre el texto literal: cambiar el orden de las propiedades del JSON no cambia el resultado.
Los registros de Idempotency-Key no expiran: la misma llave con un cuerpo distinto responde 409 IDEMPOTENCY_CONFLICT indefinidamente. Genera una llave nueva por cada intento de cobro, por ejemplo un UUID, y guárdala junto a ese intento: el reintento de esa llamada usa la misma llave, y un intento nuevo, otra. Una llave fija en tu código, o copiada de un ejemplo, sólo sirve para la primera sesión.
La API no expone hoy un código de error para dos solicitudes simultáneas con la misma llave mientras la primera se procesa. No envíes la misma llave en paralelo; reintenta solo después de un timeout o de una respuesta perdida.