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

Primero, se debe instalar las dependencias:

npm install svix

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

Nombre	Descripción
`instrument.created`	Este evento se activa cuando se crea un instrumento en Akua. El valor devuelto es el ID del instrumento relacionado.
`instrument.deleted`	Este evento se activa cuando se elimina un instrumento en Akua. El valor devuelto es el ID del instrumento relacionado.
`instrument.updated`	Este evento se activa cuando se actualiza un instrumento en Akua. El valor devuelto es el ID del instrumento relacionado.

Evento de Ejemplo

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

Payments

Nombre	Descripción
`payment.authorization.processed`	Este evento ocurre cuando una autorización de pago se procesa con éxito.
`payment.cancel.processed`	Este evento ocurre cuando una cancelación de pago se procesa con éxito.
`payment.capture.manual.processed`	Este evento ocurre cuando una captura manual de pago se procesa con éxito.
`payment.capture.automatic.processed`	Este evento ocurre cuando una captura automática de pago se procesa con éxito.
`payment.authorization.rejected`	Este evento ocurre cuando una autorización de pago es rechazada.
`payment.refund.rejected`	Este evento ocurre cuando una solicitud de reembolso es rechazada.
`payment.account-status.rejected`	Este evento ocurre cuando un pago es rechazado debido a problemas con el estado de la cuenta.
`payment.adjust.rejected`	Este evento ocurre cuando un ajuste de pago es rechazado.
`payment.cancel.rejected`	Este evento ocurre cuando una solicitud de cancelación de pago es rechazada.
`payment.capture.cleared`	Este evento ocurre cuando una captura de pago es liquidada.
`payment.refund.cleared`	Este evento ocurre cuando un reembolso es liquidado.
`payment.clearing.requested`	Este evento ocurre cuando un pago es presentado ante la network.
`payment.clearing.processed`	Este evento ocurre cuando se recibe la respuesta del procesamiento del clearing un pago por parte de la network.
`payment.processing.failed`	Este evento ocurre cuando falla el procesamiento de un pago.

Evento de Ejemplo

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

Failed Validation Payments

Nombre	Descripción
`payment.validation.failed`	Este evento ocurre cuando falla la validación de un pago.

Evento de Ejemplo

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

Merchants

Nombre	Descripción
`merchant.created`	Este evento ocurre cuando se crea un nuevo comerciante en la plataforma de Akua.

Evento de Ejemplo

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

Contracargos

Nombre	Descripción
`chargeback.created`	Este evento ocurre cuando se crea un nuevo contracargo en la plataforma de Akua.
`chargeback.updated`	Este evento ocurre cuando hay un cambio en el estado del contracargo en la plataforma de Akua.

Evento de Ejemplo

{
  "type": "chargeback.created",
  "data": {
    "id": "cbk-d3i21amhj2jm7d5vcrkg",
    "merchant_id": "mer-d1oh04mv24kmg63vtmsg",
    "status": "PENDING"
  }
}

Guía de uso para Webhooks

Verificación de Autenticidad de los Webhooks

Obtención del endpoint_secret

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

Eventos

Instruments

Evento de Ejemplo

Payments

Evento de Ejemplo

Failed Validation Payments

Evento de Ejemplo

Merchants

Evento de Ejemplo

Contracargos

Evento de Ejemplo

Obtención del `endpoint_secret`