Entrega y reintentos

En pocas palabras

IDPOS le reintenta si su sistema no responde a tiempo. Para confirmar que recibió un evento, responda con un código 2xx. Si no lo hace, IDPOS vuelve a enviarlo siguiendo un calendario de reintentos.

Por eso un mismo evento puede llegar más de una vez y fuera de orden: su integración debe descartar duplicados y no depender del orden.

Entrega al menos una vez

IDPOS entrega cada evento al menos una vez, no exactamente una. Diseñe su idempotencia desde el principio.

Qué cuenta como entregado

Situación	Resultado
Su endpoint responde con cualquier código 2xx	Entregado. No se reintenta.
Su endpoint responde con cualquier código que no es 2xx	Envío fallido. Se reintenta.
Error de conexión (no se pudo establecer la conexión)	Envío fallido. Se reintenta.
Se agota el tiempo de espera	Envío fallido. Se reintenta.
El cuerpo del evento supera los 5 MiB (5 242 880 bytes)	No se envía. El evento falla y no se reintenta.

No use redirecciones

IDPOS puede seguir una redirección 3xx y evaluar la respuesta final, sin garantizar que se conserven el método POST ni el cuerpo del envío. Registre la URL final de su endpoint.

Tiempo de espera

Parámetro	Valor
Tiempo de espera por defecto	30 segundos
Rango configurable por suscripción	De 1 a 60 segundos

Responda primero y procese el evento después, en segundo plano. Una respuesta lenta se trata igual que una respuesta fallida y genera un reintento, aunque su sistema haya procesado el evento.

Calendario de reintentos

Con la configuración por defecto, IDPOS hace como máximo 5 intentos de envío por evento (el primero y 4 reintentos).

Intento	Espera desde el intento anterior	Tiempo acumulado mínimo desde el primer intento
1	Inmediato	0
2	60 segundos	1 minuto
3	5 minutos	6 minutos
4	15 minutos	21 minutos
5	1 hora	1 hora y 21 minutos

El tiempo acumulado no incluye lo que tarde su servidor en responder en cada intento.

Si falla el último intento, el evento no se vuelve a enviar de forma automática. IDBI puede reiniciar el envío de un evento fallido; en ese caso se vuelve a intentar con el mismo calendario.

Nota

El número máximo de intentos y el tiempo de espera son valores por defecto que pueden ajustarse por suscripción. Si necesita otros valores, solicítelos a IDBI.

Qué cambia entre intentos

Elemento	Entre reintentos
X-Webhook-Id y event_id del cuerpo	No cambian. Identifican el evento.
X-Webhook-Timestamp	Cambia en cada intento.
X-Webhook-Signature	Cambia en cada intento, porque depende de la marca de tiempo.

Verifique siempre con las cabeceras de la petición que está recibiendo: consulte Autenticación y firma.

Duplicados

Un mismo evento puede llegar más de una vez. Ocurre, por ejemplo, si su servidor procesó el evento pero la respuesta no llegó a IDPOS y, por eso, se reintentó.

Estrategia	Cómo aplicarla
Deduplicar por evento	Guarde el event_id del cuerpo de cada evento procesado y descarte los que ya vio. Léalo después de verificar la firma.
Deduplicar por entidad	Use data.id junto con event_type como segunda clave: por ejemplo, el par Pago completo (order.paid_in_full) y el id de la orden.
Operaciones idempotentes	Diseñe el procesamiento de modo que repetirlo no cambie el resultado.

Deduplique por event_id y por event_type + data.id

El event_id del cuerpo está cubierto por la firma. La cabecera X-Webhook-Id no lo está: no la use como única clave de deduplicación.

data.id no basta por sí solo: la misma orden genera varios eventos (Orden aceptada, Pago completo y Orden entregada: order.accepted, order.paid_in_full, order.delivered) con el mismo data.id. Combínelo siempre con event_type.

Orden de los eventos

Sin orden garantizado

IDPOS no garantiza el orden de entrega. Un evento puede llegar antes que otro que ocurrió primero, sobre todo cuando hay reintentos de por medio. Por ejemplo, Orden entregada (order.delivered) podría llegar antes que una Orden aceptada (order.accepted) que se está reintentando.

Recomendación	Motivo
No asuma que los eventos llegan en el orden en que ocurrieron.	Los reintentos alteran el orden.
Use las fechas del evento (created_at, sold_at, paid_at) y el estado (status) para decidir qué información es más reciente.	Evita sobrescribir datos nuevos con datos viejos.
Si recibe un evento de una entidad que aún no conoce, guárdelo igualmente.	El evento anterior puede llegar después.

Siguiente paso

Revise el catálogo de eventos y la estructura común de los envíos.