Webhook Setup

For Liquidity Partners to communicate status updates with the Client during workflows like KYB/KYC, Swap, Onramp, and Offramp, the Client must furnish the API endpoint for webhook notifications. Additionally, the client must configure or update their webhook URL for receiving webhooks in both the Sandbox and Production environments using the Set/Update Webhook URL.

• eventType will determine which workflow the status update belongs to.

• referenceId will allow Client to determine which object to connect the status update to. The reference ID is different depending on the eventType.

• metadata will contain additional information to help Client process webhook notifications.

{
 "referenceId": string | number,  (transactionId for onramp,offramp. clientCustomerId/submissionId for kyc/kyb)
 "eventType": string,    (onramp, offramp, kyc, kyb, fiatAccount, swap, virtual_account)
 "status": string,
 "metadata": json,
}

---

AUTHENTICATION

Ensure the webhook is authentic and untampered using HMAC SHA512.

---

• Verifies Onramp webhook authenticity using HMAC-SHA512.

• The request body is JSON-stringified and base64-encoded to generate the X-ONRAMP-PAYLOAD.

• This encoded payload is signed using HMAC-SHA512 with the YOUR_API_SECRET, forming the X-ONRAMP-SIGNATURE.

• Verification succeeds only if the generated signature matches the one provided in the headers.

• Compact JSON formatting is required to ensure consistency with Onramp’s encoding.

• Handle both lowercase and uppercase header keys to ensure compatibility (e.g., headers['x-onramp-signature'] || headers['X-ONRAMP-SIGNATURE'])

• A unique eventId is included in metadata.eventId to identify each webhook event.

• Included eventCreatedAt timestamp to ensure accurate tracking and processing of the event.

• If a 200 OK response is not received, the webhook is retried up to 5 times with the same eventId, ensuring reliable and idempotent delivery.

Sample KYC response with eventId and eventCreatedAt

{
    "status": "FAILED",
    "metadata": {
        "customerId": "cM3qZo3J_1019",
        "eventId": 22,
        "eventCreatedAt": "2023-11-17T13:33:14.000Z"
    },
    "referenceId": "b8225c3a-0d96-4bd8-bd3c-e7d8e82ebcbb",
    "eventType": "KYC"
}

HEADERS

NAME	TYPE	DESCRIPTION
X-ONRAMP-PAYLOAD	String	payload generated for the request
X-ONRAMP-SIGNATURE	String	signature generated for the request

Sample implementation for authenticating WhiteLabel webhooks:

NODE.js

const CryptoJS = require('crypto-js');
const dotenv = require('dotenv');
dotenv.config({ path: 'YOUR_.ENV_PATH' });

exports.authenticateOnrampWhiteLabelWebhook = (req, res, next) => {
  try {
    const data = req.body;
    const receivedSignature = req.headers['x-onramp-signature'] || req.headers['X-ONRAMP-SIGNATURE'];
    const receivedPayload = req.headers['x-onramp-payload'] || req.headers['X-ONRAMP-PAYLOAD'];

    const encodedPayload = Buffer.from(JSON.stringify(data)).toString('base64');
    const generatedSignature = CryptoJS.HmacSHA512(encodedPayload, process.env.ONRAMP_API_SECRET).toString(CryptoJS.enc.Hex);

    if (encodedPayload === receivedPayload && generatedSignature === receivedSignature) {
      return next();
    } else {
      return res.status(401).send({ status: 0, error: 'Invalid signature' });
    }
  } catch (err) {
    return res.status(500).send({ status: 0, error: 'Internal error' });
  }
};

PYTHON

import hmac
import hashlib
import base64
import json
import os

def verify_onramp_webhook(request_data, headers):
    """
    Verifies Onramp webhook signature.

    Args:
        request_data (dict): The JSON body of the request.
        headers (dict): Headers of the incoming webhook request.

    Returns:
        bool: True if the signature is valid, False otherwise.
    """
    try:
        # Get values from headers (case-insensitive)
        received_signature = headers.get('x-onramp-signature') or headers.get('X-ONRAMP-SIGNATURE')
        received_payload = headers.get('x-onramp-payload') or headers.get('X-ONRAMP-PAYLOAD')

        # Step 1: Create base64-encoded payload from JSON data
        json_string = json.dumps(request_data, separators=(',', ':'))
        encoded_payload = base64.b64encode(json_string.encode('utf-8')).decode('utf-8')

        # Step 2: Generate HMAC SHA512 signature using your shared API secret
        secret_key = os.getenv("ONRAMP_API_SECRET").encode('utf-8')
        generated_signature = hmac.new(secret_key, encoded_payload.encode('utf-8'), hashlib.sha512).hexdigest()

        # Step 3: Match both encoded payload and signature
        return (encoded_payload == received_payload) and (generated_signature == received_signature)

    except Exception:
        return False