Buenas prácticas y deduplicación

Estas son las prácticas esenciales de seguridad e implementación para construir integraciones de webhook seguras y fiables.

Seguridad

• Usa siempre una URL segura (HTTPS). Las conexiones HTTP no están cifradas y son vulnerables a ataques man-in-the-middle.
• Usa un método de autenticación (BEARER, API_TOKEN o BASIC_AUTH) al crear tu webhook, para evitar peticiones no autorizadas.
• Valida la estructura y el contenido del evento antes de procesarlo: comprueba que los campos requeridos estén presentes y tengan el tipo esperado.

Implementación

• Confirma la recepción de inmediato con un 200 OK. Tonder tiene un timeout de 30 segundos; responde primero y procesa la lógica de negocio en segundo plano.
• Usa metadata.external_id para deduplicar. Guarda los IDs procesados temporalmente (24-48 horas) y compáralos antes de procesar nuevos eventos —el mecanismo de reintento puede enviar el mismo evento varias veces.
• Guarda registros detallados del payload completo, el estado de procesamiento y los errores, con timestamps e IDs de evento.
• Maneja los errores con elegancia. Envuelve el procesamiento en bloques try-catch para que un webhook fallido no tire toda tu aplicación.

Checklist de deduplicación

• Deduplica por metadata.external_id (funciona en formatos Short + Long).
• Mantén un índice idempotency_key en 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 Declined para retiros como estado terminal.

Siguientes pasos