Webhooks duales

En el modelo Híbrido, una sola transacción puede emitir dos webhooks: uno en formato Long (de Hosted/SDK, para la tarjeta) y otro en formato Short (de API Direct, para métodos no-tarjeta, retiros y reembolsos). Esto es por diseño.

Por qué llegan webhooks duplicados

Como cada leg de tu integración (SDK/Hosted para tarjetas, API Direct para todo lo demás) tiene su propio canal de webhooks, recibirás notificaciones de ambos. Un mismo pago puede generar un evento Pending y luego un Success por cada canal involucrado.

Qué necesitas configurar

• Dos endpoints de webhook, uno por estilo de integración. Con Webhooks 2.0, suscribe el endpoint de tarjetas a los eventos de Sesiones de checkout — Hosted y SDK y el otro a Pagos — API Direct y Retiros (ver el Catálogo de eventos). Sin Webhooks 2.0 cada URL registrada recibe ambos formatos, así que enruta por formato en tu handler.
• Lógica de manejo separada: webhooks estilo Hosted/SDK para las transacciones con tarjeta, y estilo API Direct para los demás métodos, retiros y reembolsos.

Lista de deduplicación

• Con Webhooks 2.0, deduplica con el header webhook-id — un reintento o un reenvío trae el mismo. Sin Webhooks 2.0, deduplica con id + event_type. Correlaciona con metadata.external_id, que se repite en cada evento de una transacción y funciona en los formatos Short + Long.
• Guarda los webhook-id procesados durante al menos 60 días —un evento se puede reenviar mientras se conserva.
• 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 los cinco estados terminales de retiros — Success, Declined, Cancelled, Failed y Returned; Returned llega después de Success.

Siguientes pasos