Entrega y reintentos
Qué cuenta como entrega exitosa, cuándo reintenta Tonder y cómo evitar duplicados.
El sistema de webhooks de Tonder está diseñado para la fiabilidad. Si tu endpoint no está disponible temporalmente, reintentaremos la entrega automáticamente.
Cómo funciona la entrega
Ocurre un cambio de estado de la transacción o un evento.
Tonder envía una petición POST a tu endpoint.
La respuesta de tu endpoint determina el siguiente paso.
Según la respuesta, el evento se marca como completo o se agenda un reintento.
Política de reintentos
| Ajuste | Valor | Descripción |
|---|---|---|
| Máximo de intentos | 3 | Intentamos entregar el webhook hasta 3 veces. |
| Timeout de procesamiento | 30 segundos por intento | Tu endpoint debe responder en 30 segundos. |
| Intervalo de reintento | 60 segundos | Esperamos 60 segundos antes de reintentar. |
| Ventana total de reintentos | ~3 minutos | Tiempo máximo reintentando un mismo evento. |
Criterios de éxito y falla
Una entrega es exitosa si tu endpoint responde con un código 2xx dentro de los 30 segundos.
Cualquier otra respuesta es una falla y se agenda un reintento. Escenarios que disparan
reintentos:
- Errores
4xx(400, 401, 404, etc.) — errores del cliente. - Errores
5xx(500, 502, 503, etc.) — errores del endpoint. - Timeouts cuando no se recibe respuesta tras 30 segundos.
Dead Letter Queue (DLQ)
Tras 3 intentos fallidos, el evento se mueve a una Dead Letter Queue para inspección manual. Los eventos fallidos se guardan 30 días, son accesibles desde el dashboard o vía soporte, y pueden reintentarse manualmente tras corregir el endpoint.
Consideraciones de implementación
- Confirma la recepción de inmediato con un
200 OKpara evitar timeouts. - Usa
metadata.external_idpara deduplicar y no procesar el mismo evento dos veces. - Guarda registros detallados de cada webhook para depuración.
- Asegura que un payload malformado o un error de procesamiento no tire tu sistema.
- Deduplica por
metadata.external_id(funciona en formatos Short + Long). - Mantén un índice
idempotency_keyen tu base de datos. - En modo Híbrido, trata el par Pending + Success como intencional.
- Verifica siempre el estado final con
GET /api/v1/transactions/{id}/. - Maneja
Declinedpara retiros como estado terminal.