Webhooks

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

Variable	Type	Description
`apiKey`	`string`	The Onramper API Key through which the transaction was processed.
`country`	`string`	ISO 2 letter country code.
`inAmount`	`number`	For Onramp transactions, contains the fiat amount requested.
`onramp`	`string`	ID of the provider that handled the transaction.
`onrampTransactionId`	`string`	The provider transaction ID.
`outAmount`	`number`	For Onramp transactions, contains the Crypto Currency delivered.
`partnerContext`	`string`	`optional` `partnerContext` can be supplied as `string` parameter to the widget and will be returned via the webhooks.
`paymentMethod`	`string`	Contains the Payment Method ID.
`sourceCurrency`	`string`	For Onramp transactions, contains the Fiat Currency ID.
`status`	`string`	String representing the status of the transaction. `pending \| paid \| failed \| completed`
`statusDate`	`string`	Date/Time string in simplified extended ISO format ISO 8601.
`targetCurrency`	`string`	For Onramp transactions, contains the Crypto Currency ID.
`transactionHash`	`string`	A transaction hash, where available / applicable.
`transactionId`	`string`	Onramper transaction ID.
`transactionType`	`string`	Type of transaction. `buy \| sell`
`walletAddress`	`string`	The 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.

The endpoint from the provided URL should handle POST requests with JSON body of the format described above.

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