Webhooks

Onramper uses webhooks for all providers to notify you when a transaction status has changed.

VariableTypeDescription
apiKeystringThe Onramper API Key through which the transaction was processed.
countrystringISO 2 letter country code.
inAmountnumberFor Onramp transactions, contains the fiat amount requested.
onrampstringID of the provider that handled the transaction.
onrampTransactionIdstringThe provider transaction ID.
outAmountnumberFor Onramp transactions, contains the Crypto Currency delivered.
partnerContextstringoptional partnerContext can be supplied as string parameter to the widget and will be returned via the webhooks.
paymentMethodstringContains the Payment Method ID.
sourceCurrencystringFor Onramp transactions, contains the Fiat Currency ID.
statusstringString representing the status of the transaction. pending | paid | failed | completed
statusDatestringDate/Time string in simplified extended ISO format ISO 8601.
targetCurrencystringFor Onramp transactions, contains the Crypto Currency ID.
transactionHashstringA transaction hash, where available / applicable.
transactionIdstringOnramper transaction ID.
transactionTypestringType of transaction. buy | sell
walletAddressstringThe wallet address where the crypto was delivered.

Setting up Webhooks

To enable webhooks for any ApiKey contact your Customer Success Manager and send your desired webhook URL and the corresponding ApiKey you want to enable webhooks for.

Validating payloads from Onramper

When your webhook secret is shared, Onramper uses it to create a hash signature with each payload. This hash signature is included with the headers of each request as X-Onramper-Webhook-Signature.

You should calculate a hash using your secret, and ensure that the result matches the hash from Onramper. Onramper uses an HMAC hex digest to compute the hash.

Node.js Typescript example

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);
};