Webhooks son callbacks que notifican eventos en tu cuenta. Un webhook hace una petición HTTP a tu aplicación (normalmente por el método POST), cuyo body contiene un objeto que describe el evento asociado.Por ejemplo: cuando se genera la captura de una autorización, un webhook te permite recibir una notificación para que puedas tomar una acción, como enviar un correo de agradecimiento al cliente.Los webhooks son útiles en dos situaciones:Cuando un evento generado no es resultado directo de una llamada a la API; por ejemplo, un chargeback.
Cuando servicios o funcionalidades necesitan la respuesta de una llamada, pero no la ejecutan directamente; por ejemplo, un servicio de contabilidad que necesita actualizar los registros cuando se genera una transacción.
Actualizar la membresía de un cliente en tu base de datos cuando el pago es exitoso.
Registrar un asiento contable después de que se realiza una transacción.
Los webhooks de pagos presenciales solo se pueden configurar desde la Console. Los webhooks por API no están soportados.
Consumir un webhook#
Crea un endpoint para recibir webhooks: solo agrega a tu aplicación una nueva ruta con la URL que quieras. Los datos del webhook se envían en formato JSON en el body de la llamada POST.
Seguridad#
Cifrado#
Puedes usar URLs HTTP o HTTPS para los webhooks. Se recomienda HTTPS si manejas datos sensibles o si quieres protegerte contra ataques de repetición.Autenticación#
Para verificar que las notificaciones de webhook provienen de Kushki, revisa las siguientes cabeceras en cada petición entrante:| Cabecera | Descripción |
|---|
X-Kushki-Key | El ID de tu comercio. |
X-Kushki-Signature | Firma HMAC SHA256 del body de la petición + el timestamp, usando tu ID de firma de webhook. |
X-Kushki-SimpleSignature | Firma HMAC SHA256 del valor de X-Kushki-Id, usando tu ID de firma de webhook. |
X-Kushki-Id | Fecha de la petición en formato timestamp Unix. |
IPs estáticas de Kushki para el envío de webhooks:Producción: 34.230.185.20
Cómo obtener la firma del webhook#
Ve a Desarrolladores > Webhooks en la Kushki Console. Tu firma de webhook aparece en la parte superior de la página.
Ejemplos de verificación de la firma#
X-Kushki-Signature#
X-Kushki-SimpleSignature#
Tipos de evento de webhook#
Según las operaciones que hayas integrado, el body del webhook seguirá una de estas estructuras:Pagos con tarjeta: cargo, preautorización, captura, reverso, anulación y consulta de saldo
¿Tienes una sugerencia sobre esta documentación? Contáctanos.
