Configuración e implementación

Se requieren solo cuatro pasos para su implementación:

1. Crear una aplicación y su clave secreta correspondiente
2. Crear la ruta de enlace en su servidor para conectar los dos sistemas
3. Probar la conexión del webhook
4. Validar la firma del mensaje

1.  Crear una aplicación y su clave secreta correspondiente

Una Aplicación permite agrupar los webhooks que se vayan configurando en la sesión según su preferencia. El objetivo de las Aplicaciones es poder diferenciar su uso, ya sea para utilizar diferentes ambientes (Testing, Production, etc), separar por las distintas áreas del negocio, etc.

Ingrese a Configurar > Webhooks, y pulse Agregar. Ingrese el nombre de su aplicación (ej: Producción, Pruebas, Power BI, etc) y haga clic en Crear.

Al momento de crear una aplicación se le proporcionará una clave secreta que debe ser almacenada en un lugar seguro. No debe compartir esta clave y debe tratarla como si fuera una contraseña. Este campo será utilizado para comprobar la validez del mensaje y corroborar que la información fue enviada por nuestra plataforma. Por seguridad esta clave no se puede recuperar. Si la extravía o pierde deberá generar una nueva clave.

Nota: los webhooks son configurados de manera general para toda la empresa. Independiente del proyecto desde donde se genera la acción o quien la realiza, si hay un evento configurado y activado, se enviará la notificación del evento abarcando todas las aplicaciones que lo tengan implementado.

2.  Configurar ruta de enlace

Haga clic en la Aplicación que creó en el paso 1 para ingresar a configurar los eventos.

Ingrese la URL pública que ha habilitado en su sistema donde se procesará la información enviada por nuestra plataforma. Asegúrese de activar el webhook una vez la configuración y primeras pruebas hayan finalizado.

3.  Probar la conexión

Puede usar la opción "Probar" desde el menú contextual, si requiere realizar pruebas de integración sin necesidad de modificar los datos oficiales de la sesión de la empresa. Se cargarán los datos respectivos de cada evento que serán enviados en el mensaje.

Si la URL proporcionada devuelve un código de respuesta distinto a 2xx, se reintentará enviar el mensaje nuevamente con un máximo de cinco (5) intentos. Si el último reintento falla, el webhook será desactivado. Puede revisar esta información en la pestaña Historial de cada aplicación.

Nota: el tiempo de espera de cada solicitud POST es de 15 segundos.

4.  Validar la firma del mensaje

Como medida de seguridad todas las solicitudes HTTPS realizadas desde nuestra plataforma son firmadas utilizando una clave secreta de la aplicación correspondiente. Esto le permitirá verificar que el mensaje fue enviado por Calidad Cloud y no una tercera parte.

El campo signature incluído en los encabezados de cada solicitud corresponde al código de autenticación basado en hash utilizado por nuestro sistema (HMAC con SHA-256). Para realizar la validación debe usar el cuerpo del mensaje de la solicitud para aplicar el hash mencionado, utilizando su clave secreta obtenida en el paso 1. Si la cadena de texto coincide con el campo signature, entonces el mensaje es válido y seguro.

A continuación encontrará ejemplos para implementar la validación con diferentes lenguajes de programación.

PHP

<?php
$secretKey = ''; // Clave secreta generada al momento de crear una aplicación
$jsonPayload = ''; // Contenido recibido en la solicitud en formato json
$headerSignature = ''; // Firma recibida en los headers de la solicitud con el nombre "signature"
$contentSignature = hash_hmac('sha256', $jsonPayload, $secretKey); // Generación de la firma para luego compararla con la recibida

echo $headerSignature === $contentSignature ? 'Solicitud auténtica ✓' : 'Solicitud inválida ✕';

NodeJs

const crypto = require('crypto');

const secretKey = ''; // Clave secreta generada al momento de crear una aplicación 
const jsonPayload = ''; // Contenido recibido en la solicitud en formato json 
const headerSignature = ''; // Firma recibida en los headers de la solicitud con el nombre "signature" 
const contentSignature = crypto.createHmac('sha256', secretKey).update(jsonPayload).digest('hex'); // Generación de la firma para luego compararla con la recibida

console.log(headerSignature === contentSignature ? 'Solicitud auténtica ✓' : 'Solicitud inválida ✕');

C#

using System;
using System.IO;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

namespace Signature
{
  public class Validator
  {
    public static void Main(string[] args)
    {
      // Clave secreta generada al momento de crear una aplicación
      string secretKey = "";
      byte[] key = Encoding.ASCII.GetBytes(secretKey);
     
      // Contenido recibido en la solicitud en formato json
      string jsonPayload = "";
      byte[] data = Encoding.ASCII.GetBytes(jsonPayload);
     
      // Firma recibida en los headers de la solicitud con el nombre "signature"
      string headerSignature = "";
     
      // Generación de la firma para luego compararla con la recibida
      HMACSHA256 myhmacsha256 = new HMACSHA256(key);
      MemoryStream stream = new MemoryStream(data);
      string contentSignature = myhmacsha256.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}",e), s => s );
     
      Console.WriteLine(headerSignature == contentSignature ? "Solicitud auténtica" : "Solicitud inválida");
    }
  }
}