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 5 types of webhooks:

  1. Offramp transaction
  2. Onramp transaction
  3. Acceptance transaction
  4. Deposit transaction
  5. Disbursement 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, onramp, deposit, and disbursement.

{
  "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:

/**
 * This function verifies the digital signature of an incoming webhook request.
 * It takes the string to sign, the signature, and the public key to verify the authenticity of the request.
 * 
 * @param {string} stringToSign - The string that was signed for verification.
 * @param {string} signature - The base64 encoded signature to verify.
 * @returns {boolean} - Returns true if the signature is valid, indicating the request is authentic, and false otherwise.
 */
function verifySignature(stringToSign, signature) {
  // Replace newline escape sequences with actual newline characters in the public key
  const pubKey = jwtPubKey.replace(/\\n/g, '\n')

  // Create a Verify object with the SHA256 algorithm
  const verify = crypto.createVerify('SHA256')
  // Update the Verify object with the string to sign
  verify.update(stringToSign)
  // End the Verify object
  verify.end()
  // Verify the signature against the public key
  return verify.verify(pubKey, Buffer.from(signature, 'base64'))
}

/**
 * This function generates the string that needs to be signed for webhook verification.
 * It takes the timestamp, URL, and body of the webhook request and returns a string that can be signed.
 * 
 * @param {string} timestamp - The timestamp of the webhook request in ISO 8601 format.
 * @param {string} url - The URL of the webhook endpoint.
 * @param {object} body - The request body of the webhook.
 * @returns {string} - The string to sign for verification.
 */
function createStringToSign(timestamp, url, body) {
  // Minify the request body to a JSON string
  const minifyBody = JSON.stringify(body)
  // Create a SHA256 hash of the minified body
  const hashBody = crypto.createHash('sha256').update(minifyBody)
  // Get the hexadecimal representation of the hash
  const hexBody = hashBody.digest('hex')
  // Convert the hexadecimal string to lowercase
  const lowerCaseBody = hexBody.toLowerCase()
  // Construct the string to sign in the format specified by the webhook service
  return `POST:${url}:${lowerCaseBody}:${timestamp}`
}

/**
 * This is the main function to demonstrate the webhook verification process.
 * It simulates a webhook request with a timestamp, URL, body, and signature, and then verifies the signature.
 */
function main() {
  // Simulate a webhook request
  const timestamp = new Date().toISOString() // timestamp from webhook request
  const url = '/api/webhook' // your webhook url without base url
  const body = { key: 'value' } // request body from webhook request
  const signature = 'signature' // signature from webhook request

  // Generate the string to sign based on the webhook request
  const stringToSign = createStringToSign(timestamp, url, body)
  // Verify the signature
  console.log(verifySignature(stringToSign, signature))
}

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?