Webhooks de Kushki: cómo procesar eventos de pago sin perder ni uno
Los webhooks son la fuente de verdad de tus transacciones. Te mostramos cómo verificar firmas HMAC, manejar reintentos y garantizar entrega exactamente una vez.
25 de marzo de 2026
·11 minSi tu integración actualiza el estado de un pago basándose en la respuesta del checkout, tienes un bug en producción esperando ocurrir. La respuesta del checkout puede perderse por un browser cerrado, un timeout de red o un error del cliente. Los webhooks son la única fuente de verdad confiable.
Estructura de un evento webhook
Kushki envía un POST HTTPS a tu endpoint con un payload JSON firmado. El campo event indica el tipo de evento (payment.succeeded, payment.failed, refund.created, etc.) y el campo data contiene el objeto completo de la transacción.
Verificación de firma HMAC
Cada request incluye el header X-Kushki-Signature con una firma HMAC-SHA256 del body. Verifica siempre la firma antes de procesar el evento — esto previene que actores maliciosos llamen tu endpoint con datos falsos.
Nunca proceses un webhook sin verificar la firma. Aunque tu endpoint no esté expuesto públicamente, siempre valida la autenticidad del origen.
Idempotencia: el mismo evento puede llegar dos veces
Kushki reintenta un webhook si tu endpoint no responde con HTTP 200 en menos de 5 segundos. Esto significa que el mismo evento puede llegar múltiples veces. Guarda el event.id en tu base de datos y verifica si ya fue procesado antes de ejecutar cualquier lógica de negocio.
Política de reintentos
- Intento 1: inmediato
- Intento 2: 1 minuto
- Intento 3: 10 minutos
- Intento 4: 1 hora
- Intento 5: 6 horas
- Intento 6: 24 horas
- Intento 7: 72 horas