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), cuyo cuerpo 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 estos no la realizan directamente. 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 diferente a crear cualquier otra página en tu sitio. Basta con crear una nueva ruta con la URL deseada.

Los datos del webhook son enviados en formato JSON en el body o cuerpo de la llamada POST. Todos los detalles del evento están incluidos y pueden ser usados directamente (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 tu 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 más el timestamp, utilizando tu ID de firma de Webhooks.
  • X-Kushki-SimpleSignature: Corresponde a la firma HMAC SHA256 del X-Kushki-Id, utilizando tu ID de firma de webhooks.
  • X-Kushki-Id: Fecha en formato timestamp (YYYY-MM-DD).

Utilizando estos encabezados, deberás comparar con la firma generada desde tu lado, empleando el ID de firma de webhooks de tu comercio que puedes encontrar en la consola. Puedes usar 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.