Rampable Webhook

The Rampable Webhook service allows your application to receive real-time updates on the status of transactions initiated through the Rampable platform. This document provides an overview of the webhook workflow and instructions for integrating it into your application.

Overview

When a user initiates a transaction on the Rampable platform, your application will receive a webhook notification via an HTTP POST request. These notifications will keep you informed about the progress of the transaction.

Registration

We have 3 types of webhooks:

  1. Offramp transaction
  2. Onramp transaction
  3. Acceptance transaction

You can register for each webhook type individually. To start receiving webhook notifications, you need to register your webhook URL with Rampable. Follow these steps:

  1. Contact your Rampable representative and provide them with the URL where your application will receive the webhook notifications, along with the specific webhook type(s) you want to register for.
  2. Rampable will register your webhook URL and provide you with a verification key. This key will be used to verify the authenticity of incoming webhook requests.

Schema

Each webhook request will include the following headers:

  • Content-Type: application/json: Indicates that the request body is in JSON format.
  • X-TIMESTAMP: <ISO_8601_timestamp>: The timestamp when the webhook was generated, in ISO 8601 format (e.g., 2024-08-23T10:00:00Z).
  • X-SIGNATURE: <base64_signature>: A digital signature used to verify the authenticity of the request. This signature is generated using the verification key provided during registration.

Request Body

The webhook request body will contain information about the transaction status. transactionStatus will be based on transaction current status. Status reference for offramp and onramp.

{
  "orderId": "orderId",
  "responseCode": "200",
  "responseMessage": "success",
  "transactionStatus": "processed"
}

Verify incoming webhook

To ensure the authenticity of incoming webhook requests, you should verify the digital signature included in the X-SIGNATURE header. Here's an example of how to do this in Node.js:

/**
 * Verifies a digital signature against a JSON stringified request body using the provided public key.
 *
 * @param {string} rampablePublicKey - The public key in base64-encoded format used to verify the signature.
 * @param {string} stringToSign - The JSON stringified request body that was signed. 
 * @param {string} signature - The base64-encoded digital signature to verify.
 * @returns {boolean} - Returns true if the signature is valid, otherwise false.
 *
 * @throws {Error} If the public key, stringToSign, or signature are invalid.
 *
 * @example
 * const requestBody = {
 *   orderId: "orderId",
 *   responseCode: "200",
 *   responseMessage: "success",
 *   transactionStatus: "processed"
 * };
 * const stringToSign = JSON.stringify(requestBody);
 * const isValid = verifySignature(
 *   'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7...',
 *   stringToSign,
 *   'MEUCIQD3r...'
 * );
 * console.log(isValid); // true or false
 */
function verifySignature(rampablePublicKey: string, stringToSign: string, signature: string): boolean {
  const pubKey = Buffer.from(rampablePublicKey, 'base64').toString('ascii').replace(/\\n/g, '\n');

  const verify = crypto.createVerify('SHA256');
  verify.update(stringToSign);
  verify.end();
  return verify.verify(pubKey, Buffer.from(signature, 'base64'));
}

Next Steps

After verifying the incoming webhook, your application can process the transaction status and take appropriate actions based on the provided information.

Was this page helpful?