Optional: Webhook Setup

📘
Optional
This step is optional and by no means needed to get a functioning Onramper integration up and running. Setting up webhooks is a way for you to always know the status of a transaction.

Endpoint configuration

Set up an endpoint on your server capable of handling POST requests. This will serve as the webhook listener. Ensure the endpoint can parse and handle JSON payloads, as this is the typical format for webhook data.

Webhook registration with Onramper

To activate webhooks for a specific ApiKey, please reach out to your Customer Success Manager. Provide them with your preferred webhook URL and the associated ApiKey for which you wish to enable webhooks.

Payload structure

The webhook will send a payload containing these specific properties:

{
    "country": "us",
    "inAmount": 100,
    "onramp": "gatefi",
    "onrampTransactionId": "8bf94c80-test-aabb-851-143835984d1d",
    "outAmount": 3.83527521,
    "paymentMethod": "creditcard",
    "partnerContext": "",
    "sourceCurrency": "usd",
    "status": "pending",  	
    "statusDate": "2023-08-09T13:15:18.725Z",
    "targetCurrency": "sol",
    "transactionId": "01H7D547TESTV2RQJ52ZAB7WF7",
    "transactionType": "buy",
    "transactionHash": "",
    "walletAddress": "testG15oy66q7cU6aNige54PxLLEfGZvRsAADjbF7D4"
}

Status property explanation

Webhook Status	Explanation
`completed`	The transaction has been successfully completed.
`paid`	The payment has been made but the transaction is not yet completed.
`pending`	The transaction is currently in progress and awaiting further action.
`new`	A new transaction has been created but no payment has been made yet.
`failed`	The transaction has failed due to an error or user action.
`canceled`	The transaction has been canceled by the user or the system.

Payload property explanation

Field	Example Value	Explanation
`country`	`us`	The country code where the transaction originated.
`inAmount`	`100`	The amount of fiat currency input by the user for the transaction.
`onramp`	`gatefi`	The name of the onramp provider handling the transaction.
`onrampTransactionId`	`8bf94c80-test-aabb-851-143835984d1d`	The unique identifier for the transaction provided by the onramp provider.
`outAmount`	`3.83527521`	The amount of cryptocurrency output from the transaction.
`paymentMethod`	`creditcard`	The method of payment used by the user (e.g., credit card, bank transfer).
`partnerContext`	`""`	Context or metadata provided by the partner, if any.
`sourceCurrency`	`usd`	The fiat currency used for the transaction.
`status`	`pending`	The current status of the transaction.
`statusDate`	`2023-08-09T13:15:18.725Z`	The date and time when the status was last updated.
`targetCurrency`	`sol`	The cryptocurrency that the fiat currency is being converted to.
`transactionId`	`01H7D547TESTV2RQJ52ZAB7WF7`	The unique identifier for the transaction provided by Onramper.
`transactionType`	`buy`	The type of transaction. Possible values are: - `buy` - `offramp`
`transactionHash`	`""`	The blockchain transaction hash, if available.
`walletAddress`	`testG15oy66q7cU6aNige54PxLLEfGZvRsAADjbF7D4`	The cryptocurrency wallet address to which the funds are sent.

Security and payload validation

Upon request for webhook registration, Onramper will provide you with a secret key. This key is used by Onramper to generate a hash signature for each payload. This signature is then included in the headers of every request under the name X-Onramper-Webhook-Signature.

For security, it's essential to compute a hash using the provided secret on your end and verify that it aligns with the hash received from Onramper. Note that Onramper employs an HMAC hex digest method to calculate this hash.

import crypto from 'crypto';

// This function will return true/false if the signature matches
const verifySignature = (signature: string, secret: string, body: string) => {
  const hash = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return (signature === hash);
};

Keeping your keys safe

NEVER embed your secret API Key in any web pages or mobile applications.
Don't store the secret API Key in any version control system.
Limit who has access to your secret API Key.

Updated 3 months ago