Webhooks

Recibe callbacks que notifican cuando ocurren eventos en tu cuenta.

Los Webhooks son callbacks que notifican cuando ocurren eventos en tu cuenta. Un webhook hará una petición HTTP a tu aplicación (usualmente mediante el método POST), en donde le cuerpo de ella contendrá un objeto que describe el evento asociado. Son increíblemente útiles y una forma sencilla para implementar reacciones a eventos.

Por ejemplo: Cuando se genera un cobro recurrente de una suscripción, un Webhook te permite recibir una notificación para que puedas tomar una acción, como enviar un email de agradecimiento al usuario.

Los Webhooks son útiles en dos situaciones:

  • Cuando se genera un evento que no es un resultado directo de una llamada a la API. Como por ejemplo el cobro de una suscripción.
  • Cuando existen servicios o funcionalidades que necesitan saber la respuesta a una llamada, pero éstos no la realizan diréctamente. Como por ejemplo un servicio de contabilidad que necesita actualizar el registro cuando se genera una transacción.

Algunos casos de uso son:

  • Actualizar la membresía de un cliente en tu base de datos cuando el pago de una suscripción es exitoso.
  • Enviar un email a un cliente cuando el pago de su suscripción falla.
  • Registrar una entrada en contabilidad cuando se realiza una transacción.

Consumir un Webhook

El primer paso para consumir un Webhook es crear un endpoint para recibirlos. No es distinto a crear cualquier otra página en tu sitio. Basta con crear una nueva ruta con la URL deseada.

Los datos del webhook son enviado en formato JSON en el body o cuerpo de la llamada POST. Todos los detalles del evento están incluidos y pueden ser usados diréctamente (luego de parsear el JSON).

Seguridad

Cifrado

Puedes usar un HTTP o una url HTTPS para los webhooks. En la mayoría de los casos, HTTP es suficiente, pero HTTPS puede ser útil si tus datos son sensibles o si deseas protegerte contra ataques de repetición, por ejemplo.

Autenticación

Dado que cualquiera podría en principio enviar una solicitud a tú endpoint, es importante verificar que estos webhooks son originados por Kushki. Por lo tanto, los Webhooks válidos contendrán estos encabezados que permiten verificar su autenticidad:

  • X-Kushki-Key: ID del comercio.
  • X-Kushki-Signature: Corresponde a la firma HMAC SHA256 del cuerpo de la petición mas el timestamp, utilizando tu ID de firma de Webhooks.
  • X-Kushki-SimpleSignature: Corresponde a la firma HMAC SHA256 del cuerpo de la petición masX-Kushki-Id, utilizando tu ID de firma de Webhooks.
  • X-Kushki-Id: Fecha en formato timestamp (YYYY-MM-DD).

Utilziando estos encabezados, deberás comparar con la firma generada desde tu lado, utilizando el ID de firma de Webhooks de tu comercio que puedes encontrar en la consola. Puedes utilizar tanto X-Kushki-Signature como X-Kushki-SimpleSignature para la comprobación.

Ejemplos

A continuación te mostramos ejemplos de cómo realizar la comprobación de la firma en los encabezados.

  • Javascript
  • Python
  • PHP
var crypto = require('crypto')
/**
* webhook_signature: Backoffice > Profile > Services > Identifiers > Webhook Signature
* x_kushki_id: Request Header
* $x_kushki_simple_signature: Request header
*/
/**
* WEBHOOK_SIGNATURE: environment variable must be set
*/
var x_kushki_simple_signature = request.headers["x-kushki-simplesignature"];
var webhook_signature = process.env.WEBHOOK_SIGNATURE;
var x_kushki_id = request.headers["x-kushki-id"];
var generated_signature = crypto.createHmac('sha256', webhook_signature).update(kushki_id).digest("hex");
if(x_kushki_simple_signature === generated_signature){
response.status("200")
} else{
response.status("401")
}
import hmac
import hashlib
import os
####
## webhook_signature: Backoffice > Profile > Services > Identifiers > Webhook Signature
## x_kushki_id: Request Header
## $x_kushki_simple_signature: Request header
####
####
## WEBHOOK_SIGNATURE: environment variable must be set
####
x_kushki_simplesignature = request.headers["x-kushki-simplesignature"]
x_kushki_id = request.headers["x-kushki-id"]
webhook_signature = os.getenv('WEBHOOK_SIGNATURE')
generated_signature = hmac.new(bytes(webhook_signature , 'utf-8'), msg = bytes(x_kushki_id , 'utf-8'), digestmod = hashlib.sha256).hexdigest()
if x_kushki_simplesignature == generated_signature:
response.status(200)
else:
response.status(401)
<?php
/**
* $webhook_signature: Backoffice > Profile > Services > Identifiers > Webhook Signature
* $x_kushki_id: Request Header
* $x_kushki_simple_signature: Request header
*/
/**
* 'WEBHOOK_SIGNATURE: environment variable must be set
*/
$webhook_signature = getenv('WEBHOOK_SIGNATURE');
$x_kushki_id = $_SERVER['HTTP_X_KUSHKI_ID'];
$x_kushki_simple_signature = $_SERVER['HTTP_X_KUSHKI_SIMPLESIGNATURE'];
$signature_generated = hash_hmac("sha256", $x_kushki_id, $webhook_signature);
if ($signature_generated === $x_kushki_simple_signature) {
header("Status: 200 OK");
} else {
header("Status: 401 Not authenticated");
}
?>

De acuerdo a lo que hayas integrado, existirán distintos tipos de cuerpo para las peticiones:


Buenas prácticas

Revisa consideraciones importantes a la hora de consumir un Webhook.