Webhooks

Webhook Payload Structure

The payload structure for webhook notifications mirrors the transaction structure described previously. Here is an example of a webhook payload for both CASHOUT and CASHIN transactions:

CASHOUT

{
  "status": "SUCCESS",
  "amount": "100.00",
  "operation": "CASHOUT",
  "conciliationId": "99649ad8436d426783a7b4828025ea3e",
  "amountWithFee": "100.00",
  "previousBalance": "2000.00",
  "details": {
    "senderName": "Sender Name",
    "senderClabe": "123456789",
    "receiverName": "Receiver Name",
    "receiverClabe": "123456789"
  }
}

CASHIN

{
  "status": "SUCCESS",
  "amount": "100.00",
  "operation": "CASHIN",
  "conciliationId": "67d87611d2de43fc9a9a44f805e23e33",
  "amountWithFee": "100.00",
  "previousBalance": "2000.00",
  "details": {
    "senderName": "Sender Name",
    "senderClabe": "123456789",
    "receiverName": "Receiver Name",
    "receiverClabe": "123456789"
  }
}

Webhook Signature

To ensure the security and authenticity of webhook notifications, each request includes a signature in the header. This signature is generated using the payload and the client's secret key.

How the Signature is Generated

The signature is created by combining the payload with your secret key using the HMAC SHA-256 algorithm.

How to verify the Signature

To verify the signature of a webhook request, follow these steps:

• Extract the Payload: Get the JSON payload from the webhook request.
• Retrieve the Signature: Extract the signature from the request header (X-Webhook-Signature).
• Generate the Signature: Use the HMAC SHA-256 algorithm with your secret key and the payload to generate a signature.
• Compare Signatures: Compare the generated signature with the signature from the request header. If they match, the webhook is verified.

Here's how you can do this in JavaScript:

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, receivedSignature, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(payload));
  const generatedSignature = hmac.digest('hex');
  
  return generatedSignature === receivedSignature;
}

// Example usage
const payload = {
  "status": "SUCCESS",
  "amount": "100.00",
  "operation": "CASHIN",
  "conciliationId": "67d87611d2de43fc9a9a44f805e23e33",
  "amountWithFee": "100.00",
  "previousBalance": "2000.00",
  "details": {
    "senderName": "Sender Name",
    "senderClabe": "123456789",
    "receiverName": "Receiver Name",
    "receiverClabe": "123456789"
  }
};

const receivedSignature = 'received-signature-from-header';
const secretKey = 'your-secret-key';

if (verifyWebhookSignature(payload, receivedSignature, secretKey)) {
  console.log('The webhook is verified.');
} else {
  console.log('The webhook verification failed.');
}

Register Webhook

To register a webhook endpoint, please contact our support team.