Introducción

Webhooks son callbacks que notifican eventos en tu cuenta. Un webhook hará una solicitud HTTP a tu aplicación (normalmente por el método POST), cuyo cuerpo contendrá un objeto que describe el evento asociado. Son increíblemente útiles y una forma simple 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 realizan directamente. Por ejemplo, un servicio contable que necesita actualizar los registros contables cuando se genera una transacción.

Estos son algunos casos en los que se usan los Webhooks:

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 de destino para recibirlos. No es diferente de crear cualquier otra página de tu sitio web. Simplemente crea una nueva ruta con la URL que quieras.

Los datos del Webhook se envían en formato JSON en el cuerpo 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 solicitud a tu endpoint de destino, por lo 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 cuerpo de la solicitud, más el timestamp, usando el ID de firma de tu Webhook.

X-Kushki-SimpleSignature: Corresponde a la firma HMAC SHA256 del X-Kushki-Id, usando el ID de firma de tu 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 validarla como comprobación adicional.
UAT: 54.208.105.247
Producción: 34.230.185.20

Debes usar estas cabeceras para comparar la firma generada de tu lado con el ID de firma de Webhooks de tu comercio, que encuentras en la consola. Puedes usar tanto 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 Consola. Para hacerlo, ve a Desarrolladores > Webhooks. En la parte superior puedes copiar fácilmente la firma del webhook.

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 cuerpo para las solicitudes:

Pagos con tarjeta

Reembolsos

Consumir un Webhook#

Seguridad#

Cifrado#

Autenticación#

¿Cuál es la IP desde la que Kushki envía las notificaciones?#

¿Cómo obtener la firma del Webhook?#

Ejemplos#

X-Kushki-Signature#

X-Kushki-SimpleSignature#