Webhooks Set Up

Introduction

Webhooks allow you to receive real-time notifications about the statuses of your payments and payouts, such as successful completion, failure, or cancellation. These notifications are sent whenever there are changes in the status of your transactions.

How to Use

There are two ways to configure webhooks: you can set up webhooks globally or specify them individually for each payment or payout.

1. Global Webhook

A global webhook URL applies to all your payments and payouts. Any changes in their statuses will trigger a notification sent to this designated URL.

• Go to Merchant Account → Settings → API Settings → Webhook → Change.

• Enter your desired webhook URL and save the changes.

1. Individual Webhook

You can also specify a webhook URL for each individual payment or payout you create. This provides more granular control over notifications. If a webhook URL is not specified during payment/payout creation, the global webhook URL (if set) will be used.

Here's an example of how you can include the webhookUrl in the request body using curl for an individual payment:

curl --request POST \
  --url https://api.bitnbox.io/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
  "amount": 1,
  "platformFeeByUser": false,
  "currency": "<string>",
  "network": "<string>",
  "customerId": "<string>",
  "customerIp": "<string>",
  "orderId": "<string>",
  "additionalData": "<string>",
  "webhookUrl": "https://example.com/webhook"
}'

How to Check Signature

To ensure the integrity and authenticity of the data received through webhooks, it's crucial to verify the x-signature in the headers against the request body using your secure API key.

Here's a breakdown of the verification process:

1. Retrieve the x-signature from the request headers.

2. Compute a signature using your API key and the request body.

3. Compare the computed signature with the x-signature from the headers.

Example

const crypto = require('crypto');

// Function to verify signature
function verifySignature(apiKey, requestBody, signatureHeader) {
    // Compute the signature using the API key and the request body
    const computedSignature = crypto.createHmac('sha256', apiKey)
                                    .update(requestBody)
                                    .digest('hex');

    // Compare the computed signature with the signature from the headers
    return computedSignature === signatureHeader;
}

// Example data
const apiKey = 'YOUR-API-KEY';
const requestBody = '{"payment_id": "123", "status": "success"}'; // Example request body
const signatureHeader = 'a2b4f9c285e38d73eeb9d3c2b478d5e1'; // Example signature from headers

// Verify the signature
const isSignatureValid = verifySignature(apiKey, requestBody, signatureHeader);

// Output result
console.log('Is signature valid?', isSignatureValid);

This process ensures that the data received is secure and has not been tampered with.