Los Webhooks permiten que tu sistema reciba notificaciones automáticas cuando ciertos eventos ocurren en nuestra plataforma. En lugar de consultar continuamente nuestra API, puedes suscribirte a eventos específicos y recibir actualizaciones mediante solicitudes HTTP.

Este mecanismo es ideal para integraciones donde se requiere reaccionar rápidamente a cambios en payments, merchants u otras acciones relevantes del negocio.

A lo largo de esta documentación, te mostraremos cómo configurar, recibir y validar Webhooks de forma segura y eficiente.

Verificación de Autenticidad de los Webhooks

Como parte de nuestro sistema de Webhooks utilizamos el servicio de Svix. Dicho eso, para la autenticidad, se deberá contar con 5 (cinco) elementos, detallados debajo:

• svix-id: Representa el ID del evento recibido.
• svix-timestamp: Representa el timestamp del evento recibido.
• svix-signature: Listado de firmas utilizado en base64.
• payload: Es el payload del evento recibido.
• endpoint_secret: Este se puede obtener luego de crear el endpoint.

Si deseas ver mas información, podes hacer click acá.

Obtención del endpoint_secret

Ya sea una vez creado el webhook, o en la recepción del mensaje, se puede encontrar el webhook-id. El mismo sigue el formato de:

wbk-d0idtusqj6bnldiskhig

Para los eventos recibidos, dentro de los headers llega una key: x-webhook-id con el valor del mismo.

Para conocer el valor de la endpoint_secret, se puede consultar directamente con el endpoint.

El valor del secreto se vería de la siguiente manera:

whsec\_Ul4flatLiGgKO86IEKQenRVXsLWNbzLB

Ejemplo de implementación de la validación con JavaScript

1. Primero, se debe instalar las dependencias:

npm install svix

2. Ejecuta el siguiente código de ejemplo con los valores mencionados:

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
wh.verify(payload, headers);

Puedes encontrar más ejemplos de código con diferentes lenguajes dentro de la documentación de Svix.

Eventos

Debajo se listan los diferentes eventos a los cuales es posible subscribirse.

Instruments

Evento de Ejemplo

{
  "type": "instrument.created",
  "data": {
    "instrument_id": "ins-cvnuebmpc9vs0p5lult0"
  }
}

Payments

Evento de Ejemplo

{
  "type": "payment.authorization.processed",
  "data": {
     "payment_id": "pay-d07u8e218e1elk12b92g",
     "transaction_id": "trx-d0gv1122dpo29a8d7l4g",
     "trace_id": "`{client_trace_id}`"
  }
}

Failed Validation Payments

Evento de Ejemplo

{
  "type": "payment.validation.failed",
  "data": {
    "trace_id": "`{client_trace_id}`",
    "error_code": "invalid_request",
    "error_type": "validation",
    "message": "invalid payment"
  }
}

Merchants

Evento de Ejemplo

{
  "type": "merchant.created",
  "data": {
    "merchant_id": "mer-ctil999v78d0bqciquc0",
    "name": "Once Market",
    "organization_id": "org-ctil999v78d0bqciquc0"
  }
}