Overview

OpenXSwitch - Webhook Overview

Introduction

Webhooks in OpenXSwitch allow you to receive real-time notifications about important events, such as updates to transfers, orders, withdrawals, or deposits. For example, you can be notified when a withdrawal is initiated, an order is executed, or a deposit is confirmed.

This guide explains how to set up and secure webhooks for seamless integration with the OpenXSwitch API.

Setting Up Webhooks

Step 1: Add Webhook URL and Secret

• Navigate to the General Section and select Webhook.
• Add your webhook endpoint, webhook secret, and select the events you wish to subscribe to (e.g., withdraw, deposit, transfer).
• ....
• ....

Step 2: Verify Webhook Setup

To ensure your webhooks are functioning correctly, you can use the OpenXSwitch Simulation API. This allows you to simulate real events, such as transaction updates or deposit confirmations, and verify that your webhook endpoint processes them as expected.

Webhook Structure

When an event occurs, OpenXSwitch will send a JSON payload via HTTP POST method to your webhook URL. The payload format is as follows:

JSON

{
  "requestId": "",
  "method": "deposit.accepted",
  "timestamp": "",
  "params": {
    .....
  }
}

👍

For details about specific event types and their status, refer to the Webhook Events Documentation .

Securing Your Webhooks

To ensure that the webhook requests are legitimate and not coming from unauthorized sources, you should verify the X-Webhook-Signature HTTP header sent with each event. This header contains the SHA256 signature of the request body, generated using your webhook secret.

Verification Example in Node.js

Here's an example of how to verify the webhook signature in Node.js:

Node.js

const crypto = require('crypto');

// Your webhook secret
const secret = 'your_webhook_secret';

// The raw body of the webhook event (as a string)
const body = '{"requestId": "","method": "deposit.accepted","timestamp": "","params": {.....}}';

// The signature from the X-Webhook-Signature header
const signature = req.headers['x-webhook-signature'];

// Create the HMAC
const hmac = crypto.createHmac('sha256', secret);
hmac.update(body);
const digest = hmac.digest('hex');

// Compare the generated HMAC digest with the signature
if (digest === signature) {
  console.log('Webhook signature is valid.');
} else {
  console.log('Invalid webhook signature.');
}

Python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = "your_webhook_secret"

@app.route("/webhook", methods=["POST"])
def verify_webhook():
    received_signature = request.headers.get("x-webhook-signature", "")
    raw_body = request.data

    computed_hmac = hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()

    if hmac.compare_digest(computed_hmac, received_signature):
        print("Webhook signature is valid.")
        return jsonify({"status": "success"}), 200
    else:
        print("Invalid webhook signature.")
        return jsonify({"error": "Invalid signature"}), 401

if __name__ == "__main__":
    app.run(port=3000)

PHP

<?php
$secret = 'your_webhook_secret';
$headers = getallheaders();
$signature = $headers['x-webhook-signature'] ?? '';

$rawBody = file_get_contents('php://input');
$computedSignature = hash_hmac('sha256', $rawBody, $secret);

if (hash_equals($computedSignature, $signature)) {
    http_response_code(200);
    echo json_encode(["status" => "success"]);
} else {
    http_response_code(401);
    echo json_encode(["error" => "Invalid signature"]);
}
?>