Reintentos de webhooks

Una entrega se considera exitosa con cualquier status HTTP 2xx. Una desconexión, timeout o respuesta no exitosa puede programar otro intento.

Calendario

Los tiempos son aproximados y pueden incluir variación operativa. No uses este calendario como reloj de negocio ni supongas que la ausencia de webhook implica que el pago no cambió.

Qué debe hacer el receptor

• Persistir antes de responder 2xx.
• Deduplicar por event.id.
• Mantener un timeout de respuesta corto.
• Ejecutar procesos lentos después de confirmar la recepción.
• Estar disponible durante toda la ventana de retries.
• Reconciliar pagos pendientes mediante consulta.

Responder 2xx aunque el evento ya se haya procesado. Devolver un error ante un duplicado solo provoca entregas innecesarias.

Errores permanentes y temporales

Un 5xx indica que el receptor no pudo aceptar el evento y normalmente justifica retry. Un 4xx indica que el request fue rechazado; algunas respuestas que demuestren una configuración permanentemente inválida pueden detener los intentos antes del séptimo.

No uses 400 o 410 como mecanismo habitual para descartar eventos que todavía no podés asociar. Persistilos de forma segura y reconciliá, o corregí la configuración del endpoint.

Replay

Un replay administrativo conserva el mismo event.id. Por eso el handler normal y el replay deben compartir la misma deduplicación. Si necesitás reprocesar efectos internos, hacelo mediante una herramienta propia que registre la decisión; no desactives la deduplicación del endpoint público.

Si se agotan los intentos

La API de pagos sigue siendo consultable aunque la entrega haya fallado. Usá GET /v1/payments/{payment_id} o tu proceso de conciliación para converger al estado real y contactá soporte con event.id, payment.id, ambiente y timestamps. Nunca compartas el secreto de firma.