Skip to main content
Webhooks are optional but recommended for tracking transaction status in real-time.

​
Overview

Webhooks allow you to receive automatic notifications when order events occur. Configure them in your Rampnow Partner Dashboard to stay updated on transaction statuses without polling.

​
Configuration Steps

1

Access API Hub

Navigate to the API Hub in your Rampnow Partner Dashboard.
2

Add Webhook URL

Enter your server endpoint URL that will receive webhook notifications.
Ensure you have a dedicated API endpoint set up on your server to handle incoming webhook events.
3

Select Event Types

Choose which events to receive:
  • All events - Get notified of every status change
  • Specific events - Select only the events you need

​
Order Events

Your webhook will receive notifications for these order status changes:

Processing

Order is being processed

Completed

Order successfully completed

Failed

Order failed or was cancelled

​
Implementation Example

Here’s a simple Flask server that receives webhook notifications: 
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/order/external', methods=['POST'])
def orderwebhook():
    data = request.json  
    # partner logic based on event
    return jsonify({"status": "success"}), 200
if __name__ == '__main__':
    app.run(port=3000)
Always return a 200 OK response to acknowledge receipt of the webhook.

​
Webhook Payload Schema

Find different tabs below for each product wise webhook formats.
{
  "orderUid": "asdasnd-askdjnasjkdn-aksdnaksdn",
  "externalOrderUid": "vsdasnd-askdjnasjkdn-aksdnaksdn",
  "createTime": "2024-10-01T11:59:45",
  "updateTime": "2024-10-01T12:00:00Z",
  "partnerGeneratedUid": "jkansdasd-asdjknasdkasd-aksdnasjdk",
  "orderType": "buy",
  "orderStatus": "processing | completed | failed",
  "paymentStatus": "settled",
  "paymentMode": "card",
  "srcCurrency": "USD",
  "srcChain": "fiat",
  "srcAmount": 100,
  "dstCurrency": "ETH",
  "dstChain": "ethereum",
  "dstAmount": 0.3,
  "walletAddress": "0xINF98983WKJENRIKjjDEER989",
  "walletAddressTag": "",
  "transactionHash": ["OxtransactionHash"]
}

​
Field Descriptions

FieldTypeDescription
orderUidstringUnique Rampnow order identifier
externalOrderUidstringExternal order reference
createTimestringOrder creation timestamp (ISO 8601)
updateTimestringLast update timestamp (ISO 8601)
partnerGeneratedUidstringYour internal order ID
orderTypestringTransaction type: buy or sell
orderStatusstringCurrent status: processing, completed, or failed
paymentStatusstringPayment settlement status
paymentModestringPayment method used (e.g., card, google_pay)
srcCurrencystringSource currency code
srcChainstringSource blockchain or fiat
srcAmountnumberAmount in source currency
dstCurrencystringDestination currency code
dstChainstringDestination blockchain or fiat
dstAmountnumberAmount in destination currency
walletAddressstringRecipient wallet address
walletAddressTagstringOptional wallet tag/memo
transactionHasharrayBlockchain transaction hash(es)

​
Best Practices

  • Use HTTPS endpoints only
  • Validate webhook signatures (if provided)
  • Implement rate limiting on your endpoint
  • Log all incoming webhooks for debugging
  • Return 200 OK quickly (process async if needed)
  • Implement idempotency using orderUid
  • Handle duplicate webhook deliveries gracefully
  • Set up monitoring and alerts for failures
  • Always respond with status codes
  • Implement retry logic on your side if needed
  • Store failed webhooks for manual review
  • Contact support if webhooks stop arriving

​
Testing Your Webhook

1

Set Up Local Endpoint

Run your webhook server locally on the specified port.
2

Use Tunneling Tool

Use tools like ngrok to expose your local server:
ngrok http 3000
3

Add Tunnel URL

Copy the ngrok URL and add it to your Rampnow dashboard.
4

Create Test Order

Create a test order and verify your endpoint receives the webhook.

​
Need Help?

If you encounter issues with webhook delivery or have questions about the payload structure, contact us at [email protected].