Webhook Implementation

Onramper utilizes webhooks to provide real-time notifications when a transaction status changes. This guide will walk you through the process of setting up and integrating these webhooks into your system.

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"

countrystringtrueThe country from which the transaction was initiated.
inAmountnumbertrueFor Onramp transactions, this field indicates the requested fiat amount.
onrampstringtrueThe ID corresponding to the provider for processing the transaction.
onrampTransactionIdstringtrueThe transaction ID is assigned by the provider
outAmountnumbertrueFor Onramp transactions, it contains the Crypto Currency amount delivered.
paymentMethodstringfalseThe payment method id was utilized for the transaction.
partnerContextstringfalseThe partnerContext can be provided as a string parameter to the widget, and it will be relayed back in the webhook responses.
sourceCurrencystringtrueFor Onramp transactions, this field specifies the Fiat Currency id.
statusstringtrueA string that indicates the transaction status. Possible values are: "new", "pending", "paid", "completed", "canceled", or "failed".
The specific statuses might vary among providers, depending on the webhooks they support.
statusReasonstringfalseReason for transaction status: Provides context where relevant, included selectively based on applicability.
statusDatestringtrueA date/time string formatted in the simplified extended ISO 8601 format.
targetCurrencystringtrueFor Onramp transactions, this field holds the Crypto Currency Id
transactionIdstringtrueOnramper transaction ID.
transactionTypestringtrueThe type of transaction, which can be either "buy" or "sell".
transactionHashstringfalseThe transaction hash is provided when relevant or applicable.
walletAddressstringfalseThe wallet address where the crypto was delivered.
isRecurringPaymentbooleanfalseA boolean attribute that specifies whether the transaction is recurring.

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.