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. Son muy útiles y una forma sencilla de implementar reacciones a eventos.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 usuario.Los Webhooks también 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 contables 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.
Consumir un Webhook#
El primer paso para consumir un Webhook es crear un endpoint para recibirlos. No es distinto de crear cualquier otra página de tu sitio web. Solo crea 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. Se incluyen todos los detalles del evento y puedes usarlos directamente (después de parsear el JSON).Seguridad#
Cifrado#
Puedes usar una URL HTTP o HTTPS para los webhooks. En la mayoría de los casos, HTTP es suficiente, pero HTTPS puede ser útil si manejas datos sensibles o si quieres proteger tu sistema contra ataques de repetición, por ejemplo.Autenticación#
En principio, cualquiera podría enviar una petición a tu endpoint, así que es importante verificar que estos webhooks provienen de Kushki. Por eso, para verificar su autenticidad, los Webhooks válidos contienen las siguientes cabeceras:X-Kushki-Key: ID del comercio.
X-Kushki-Signature: Es la firma HMAC SHA256 del body de la petición, más el timestamp, usando tu ID de firma de webhook.
X-Kushki-SimpleSignature: Corresponde a la firma HMAC SHA256 del X-Kushki-Id, usando tu ID de firma de webhook.
X-Kushki-Id: Fecha en formato timestamp (UNIX Time).
¿Cuál es la IP desde la que Kushki envía las notificaciones?Las notificaciones se envían desde la siguiente IP estática de Kushki; también puedes revisarla como validación adicional.Producción: 34.230.185.20
X-Kushki-Signature como X-Kushki-SimpleSignature para la verificación.¿Cómo obtener la firma del Webhook?#
Puedes ver y copiar la firma del webhook desde la Console. Para hacerlo, ve a Desarrolladores > Webhooks. En la parte superior puedes copiarla fácilmente.Ejemplos#
A continuación encontrarás algunos ejemplos de cómo verificar la firma en las cabeceras.X-Kushki-Signature#
X-Kushki-SimpleSignature#
Según las funcionalidades que hayas integrado, habrá distintos tipos de body para las peticiones:
Modified at 2026-09-11 14:41:23
