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 StatusExplanation
completedThe transaction has been successfully completed.
paidThe payment has been made but the transaction is not yet completed.
pendingThe transaction is currently in progress and awaiting further action.
newA new transaction has been created but no payment has been made yet.
failedThe transaction has failed due to an error or user action.
canceledThe transaction has been canceled by the user or the system.

Payload property explanation

FieldExample ValueExplanation
countryusThe country code where the transaction originated.
inAmount100The amount of fiat currency input by the user for the transaction.
onrampgatefiThe name of the onramp provider handling the transaction.
onrampTransactionId8bf94c80-test-aabb-851-143835984d1dThe unique identifier for the transaction provided by the onramp provider.
outAmount3.83527521The amount of cryptocurrency output from the transaction.
paymentMethodcreditcardThe method of payment used by the user (e.g., credit card, bank transfer).
partnerContext""Context or metadata provided by the partner, if any.
sourceCurrencyusdThe fiat currency used for the transaction.
statuspendingThe current status of the transaction.
statusDate2023-08-09T13:15:18.725ZThe date and time when the status was last updated.
targetCurrencysolThe cryptocurrency that the fiat currency is being converted to.
transactionId01H7D547TESTV2RQJ52ZAB7WF7The unique identifier for the transaction provided by Onramper.
transactionTypebuyThe type of transaction (e.g., buy, sell).
transactionHash""The blockchain transaction hash, if available.
walletAddresstestG15oy66q7cU6aNige54PxLLEfGZvRsAADjbF7D4The 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.