Integraciones n1coBusiness
Webhook API
¿Qué es un webhook?
Un webhook es un tipo de API basado en un parádigma de eventos. Se conoce
también como “web callback” o “HTTP push API”. Es una manera en la que un sistema
puede enviar información en el momento en el que ocurre un evento, sin que el otro
sistema deba consultar continuamente un endpoint.
1 . ¿Cómo funciona?
Primero, debes preparar en tu sistema un endpoint capaz de recibir solicitudes
POST de HTTP.
Siguiendo los pasos en la siguiente sección, configura la dirección de este
endpoint en la consola de administración de tu cuenta de hugoBusiness.
Cada vez que ocurra una nueva compra en tu tienda hugoBusiness, tu endpoint
recibirá un nuevo mensaje via POST. Puedes utilizar el contenido del mensaje en
tu sistema para almacenar los detalles de la compra, registrar un pago de
membresía, agregar saldo a la cuenta de tus clientes o lo que puedas necesitar.
Configuración del webhook
En la consola de administración n1coBusiness, debes hacer clic en el ícono de tu
cuenta en la esquina superior derecha. En el menú, selecciona Configuración.
En la pantalla de configuración, selecciona Configuración Avanzada y luego
Webhooks.
Ingresa la url pública de tu endpoint en el campo correspondiente. Opcionalmente,
puedes ingresar o generar una llave secreta que podrás utilizar posteriormente para
verificar que la data que tu endpoint está recibiendo efectivamente proviene de
n1coBusiness.
Recibiendo la data en el webhook
Para poder recibir la información de los eventos de compra, debes crear un endpoint
capáz de recibir solicitudes POST de HTTP. En la consola de administración
n1coBusiness, debes ingresar la url pública de tu endpoint siguiendo los pasos
descritos en la sección anterior. Cada vez que alguno de tus clientes haga uso de uno
de tus links de pago, tu endpoint recibirá la siguiente información en formato JSON:
Por ejemplo, supongamos que creaste un link de pago con un monto de 100. Cada
vez que uno de tus clientes realiza un pago, recibirías en tu endpoint un payload
similar a este:
Campos en la data enviada al webhook
orderId: Código de la orden relacionada con este evento. Es un identificador único
para cada orden en formato numérico. Puedes usarlo como llave para referenciar una
orden en particular.
description: Texto de descripción de la orden. Puedes utilizarlo para registrar el
detalle de lo que tu cliente está pagando.
level: Se utiliza para categorizar este evento como informativo o error. Puede ser uno
de dos valores:
Info: Este es un mensaje informativo.
Error: Este es un mensaje de error.
type: Indica cuál es el tipo de evento que ocurrió. Puede ser uno de los siguientes
valores:
Created: La orden fue creada.
Finalized: La orden fue finalizada.
Updated: Ha cambiado la fecha de expiración o el nombre de la orden.
Cancelled: La orden fue cancelada.
Deleted: La orden fue eliminada.
ShipmentStatusUpdated: El estado de envío de la orden ha cambiado.
PaymentSuccess: El pago de la orden se completó con éxito.
PaymentError: El pago de la orden se completó con éxito.
ReverseSuccess: El pago de la orden fue revertido.
ReverseError: La reversión del pago de la orden falló.
dateOccurred: La fecha y hora en la que ocurrió el evento, en formato ISO 8601.
metadata: Objeto (clave: valor) que contiene información adicional para la orden
dependiendo del tipo de la misma. En este objeto podrás encontrar el monto de la
orden y cualquier campo personalizado que hayas solicitado de tus clientes.
Cómo hacer una implementación segura
Esta sección explica cómo puedes asegurarte que la implementación de tu webhook
sea segura.
El endpoint que configures en la consola de n1coBusiness será el único lugar externo
a nuestros sistemas al que se enviaran los eventos de compra, por lo que solo
necesitas preocuparte por asegurar el origen de la información que recibes.
1 . paso 1 HTTPS
Asegurate que la url pública de tu endpoint utilize el protocolo HTTPS. Esta es la
versión segura de http en la que la comunicación entre clientes está cifrada.
1 . paso 2 SECRET
Utiliza la clave secreta que configuraste en la consola de hugoBusiness para
verificar que la data proviene directamente de nosotros y no ha sido alterada.
Para validar el payload debes
Extraer el texto de la solicitúd como un array de bytes UTF-8. Debes usar el
cuerpo entero de la solicitúd POST, incluyendo cualquier terminación de línea
Luego debes calcular el HMAC digest usando SHA256 para este array de bytes
utilizando el valor del SECRET configurado en la consola como la llave
Finalmente, utiliza Base64 para encodificar el digest.
Compara el valor resultado de este proceso con el valor que puedes encontrar en el
header X-H4B-Hmac-Sha256. Si ambos valores coinciden, esto es evidencia de que la
información de la solicitúd no ha sido alterada desde que salió de nuestros servidores.
Consulta nuestra sección de ejemplos para ver varias implementaciones en distintos
lenguajes de programación.
Ejemplo
nodejs
