Webhook - Onramp

This section explains the steps to configure callback URLs for receiving events about completed onramp transactions.

Configuring Webhook

Webhooks are configured in the merchant dashboard.

Inside the Setup section, webhooks can be added and modified under the Callback URL's section.

Generating HMAC

Signature is computed using Hash-based message authentication code (HMAC) using a secret key. The secret key is the API Secret present in your merchant dashboard.

The example implementation in Node.js is shown below:

let hmac = crypto.createHmac('sha256', apiSecret);
hmac.update(JSON.stringify(postBody));
let hash = hmac.digest('hex');
assert(hash == headers["X-Onmeta-Signature"])

Completed Order

POST{{configured_webhook_url}}

This callback will be triggered when the crypto coins are deposited to the given receiver address. It will use the configured webhook URL to send order completed details in the POST body.

info

Event Type: onramp

Make sure you have firewall rules configured to allow receiving the webhook body, otherwise your firewall might block our webhook requests.

Headers

Header	Type	Required	Description
Accept	string	Yes	application/json
Content-Type	string	Yes	application/json
X-Onmeta-Signature	string	Yes	HMAC signature for webhook verification

Request Body Parameters

Parameter	Type	Required	Description
fiat	number	Yes	Fiat amount
receiverWalletAddress	string	Yes	Wallet address receiving the crypto
buyTokenSymbol	string	Yes	Symbol of the purchased token
buyTokenAddress	string	Yes	Contract address of the purchased token
orderId	string	Yes	Unique order identifier
status	string	Yes	Order status
currency	string	Yes	Fiat currency code
chainId	number	Yes	Blockchain network chain ID
customer	object	Yes	Customer information object
txnHash	string	Yes	Blockchain transaction hash
transferredAmount	string	Yes	Amount transferred in human-readable format
transferredAmountWei	string	Yes	Amount transferred in wei
createdAt	string	Yes	Order creation timestamp
eventType	string	Yes	Event type identifier (value: "onramp")
metaData	object	No	Additional metadata including conversion rate and commission

Code Examples

cURL

curl --location -g --request POST '{{configured_webhook_url}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Onmeta-Signature: string' \
--data-raw '{
  "fiat": 100,
  "receiverWalletAddress": "0x14o2422324232323232323232232",
  "buyTokenSymbol": "MATIC",
  "buyTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "orderId": "63c93f0ffa666e128b7ab131",
  "status": "completed",
  "currency": "INR",
  "chainId": 80001,
  "customer": {
    "id": "63aaedf35b07a87b1f912023",
    "email": "test@test.com",
    "phone": {},
    "created_at": "2022-12-27T13:06:59.068Z"
  },
  "createdAt": "2023-01-19T13:01:03.289Z",
  "txnHash": "0xae21ff484bd2d05d22f6....7d1f795e9e09cda97b4d522",
  "transferredAmount": "0.01",
  "transferredAmountWei": "10000000000000000",
  "eventType": "onramp",
  "metaData": {
    "conversionRate": "90.2",
    "commission": "0"
  }
}'

Node.js

const crypto = require('crypto');

// Verify webhook signature
function verifyWebhookSignature(postBody, signature, apiSecret) {
  let hmac = crypto.createHmac('sha256', apiSecret);
  hmac.update(JSON.stringify(postBody));
  let hash = hmac.digest('hex');
  return hash === signature;
}

// Example webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-onmeta-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, apiSecret);
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  console.log('Webhook received:', req.body);
  res.status(200).json({ success: true });
});

Python

import hmac
import hashlib
import json

def verify_webhook_signature(post_body, signature, api_secret):
    message = json.dumps(post_body, separators=(',', ':'))
    hash_object = hmac.new(
        api_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    )
    computed_hash = hash_object.hexdigest()
    return computed_hash == signature

# Example webhook handler
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Onmeta-Signature')
    is_valid = verify_webhook_signature(request.json, signature, api_secret)
    
    if not is_valid:
        return {'error': 'Invalid signature'}, 401
    
    # Process webhook
    print('Webhook received:', request.json)
    return {'success': True}, 200

Response Sample

{
  "fiat": 100,
  "receiverWalletAddress": "0x14o2422324232323232323232232",
  "buyTokenSymbol": "MATIC",
  "buyTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "orderId": "63c93f0ffa666e128b7ab131",
  "status": "completed",
  "currency": "INR",
  "chainId": 80001,
  "customer": {
    "id": "63aaedf35b07a87b1f912023",
    "email": "test@test.com",
    "phone": {},
    "created_at": "2022-12-27T13:06:59.068Z"
  },
  "createdAt": "2023-01-19T13:01:03.289Z",
  "txnHash": "0xae21ff484bd2d05d22f6....7d1f795e9e09cda97b4d522",
  "transferredAmount": "0.01",
  "transferredAmountWei": "10000000000000000",
  "eventType": "onramp",
  "metaData": {
    "conversionRate": "90.2",
    "commission": "0"
  }
}

Webhook Events

Onmeta provides seven types of webhook events that allow you to receive real-time notifications when specific events occur during the onramp flow.

#	Event Name	Description
1	fiatPending	This event is triggered when a user has initialised an order but fiat deposit from user is pending.
2	orderReceived	This event is triggered when a user completes payment and Onmeta has initiated the crypto transfer.
3	InProgress(optional)	This event is triggered when the order is in-progress on the blockchain.
4	fiatReceived	This event is received on confirming that Onmeta has received payment for the onramp order.
5	transferred	This event is triggered when a user's token transfer is confirmed on the blockchain.
6	completed	This event is triggered when a user's order is completed and the user has received the tokens.
7	expired	When an order remains pending for more than three hours, the order is expired and this webhook event is triggered.

Example Webhook Request

{
  "fiat": 100,
  "receiverWalletAddress": "0xF12dc1E2EEb4d0475DE270447A92a481635caF4a",
  "buyTokenSymbol": "MATIC",
  "buyTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "orderId": "641c30286ad7d01834a02e2c",
  "status": "fiatPending",
  "currency": "INR",
  "chainId": 137,
  "customer": {
    "id": "web52390easf35fas2a25d3fffwsdae",
    "email": "documentation@onmeta.in",
    "phone": {},
    "created_at": "2023-01-04T06:58:24.968Z"
  },
  "createdAt": "2023-03-23T10:55:36.584Z",
  "txnHash": "",
  "transferredAmount": "0.990628",
  "transferredAmountWei": "990628498656169300",
  "eventType": "onramp",
  "metaData": {
    "submeta1": "metadata"
  }
}