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:
- Offramp transaction
- Onramp transaction
- 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:
- 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.
- 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.