Webhook Configuration

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

Access API Hub

Navigate to the API Hub in your Rampnow Partner Dashboard.

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.

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.

{
  "createdAt": "2024-10-01T12:00:00Z",
  "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
  "eventType": "ramp_orders.processing",
  "payload": {
    "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
    "externalOrderUid": "1eda87a5-dcfb-4a14-89d9-d0384bcb4ead",
    "createTime": "2024-10-01T11:59:45",
    "updateTime": "2024-10-01T12:00:00Z",
    "partnerGeneratedUid": "707966cf-afc0-4577-bd42-cd79a5b6f629",
    "orderType": "buy",
    "orderStatus": "processing",
    "paymentStatus": "settled",
    "paymentMode": "card",
    "srcCurrency": "USD",
    "srcChain": "fiat",
    "srcAmount": 100,
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "dstAmount": 0.3,
    "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
    "transactionHash": [
      "Ox235ebf73d0E20db0A72509207599C816510e11C9535ebf73d0E20db0A72509207599C816510e11C9"
    ]
  }
}

{
  "createdAt": "2023-11-07T05:31:56Z",
  "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
  "eventType": "tranfer_orders.processing",
  "payload": {
    "createTime": "2023-11-07T05:31:56Z",
    "dstAmount": "10000",
    "dstChain": "fiat",
    "dstCurrency": "INR",
    "externalOrderUid": "707966cf-afc0-4577-bd42-cd79a5b6f629",
    "orderStatus": "completed",
    "orderType": "unknown",
    "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
    "payinMode": "sepa",
    "paymentStatus": "accepted",
    "payoutMode": "inr_bank_transfer",
    "srcAmount": "100",
    "srcChain": "solana",
    "srcCurrency": "USDC",
    "transactionRef": [
      "KJBDUEBDNKJSBDKUAEHVFDBAJ"
    ],
    "updateTime": "2023-11-07T05:31:56Z"
  }
}

Field Descriptions

Field	Type	Description
`createdAt`	string	Webhook event creation timestamp (ISO 8601)
`eventUid`	string	Unique webhook event identifier
`eventType`	string	Event type (e.g., `orders.processing`, `orders.completed`, `orders.failed`)
`orderUid`	string	Unique Rampnow order identifier
`externalOrderUid`	string	External order reference
`createTime`	string	Order creation timestamp (ISO 8601)
`updateTime`	string	Last update timestamp (ISO 8601)
`partnerGeneratedUid`	string	Your internal order ID
`orderType`	string	Transaction type: `buy` or `sell`
`orderStatus`	string	Current status: `processing`, `completed`, or `failed`
`paymentStatus`	string	Payment settlement status
`paymentMode`	string	Payment method used (e.g., `card`, `google_pay`)
`srcCurrency`	string	Source currency code
`srcChain`	string	Source blockchain or `fiat`
`srcAmount`	number	Amount in source currency
`dstCurrency`	string	Destination currency code
`dstChain`	string	Destination blockchain or `fiat`
`dstAmount`	number	Amount in destination currency
`walletAddress`	string	Recipient wallet address
`walletAddressTag`	string	Optional wallet tag/memo
`transactionHash`	array	Blockchain transaction hash(es)

Best Practices

Security

Use HTTPS endpoints only
Validate webhook signatures (if provided)
Implement rate limiting on your endpoint
Log all incoming webhooks for debugging

Reliability

Return 200 OK quickly (process async if needed)
Implement idempotency using orderUid
Handle duplicate webhook deliveries gracefully
Set up monitoring and alerts for failures

Error Handling

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

Set Up Local Endpoint

Run your webhook server locally on the specified port.

Use Tunneling Tool

Use tools like ngrok to expose your local server:

ngrok http 3000

Add Tunnel URL

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

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].

About API

Integration methods

Webhook

Users

On/Off Ramp Orders

Transfer Orders

Webhooks

Overview

Configuration Steps

Order Events

Processing

Completed

Failed

Implementation Example

Webhook Payload Schema

Field Descriptions

Best Practices

Testing Your Webhook

Need Help?

​Overview

​Configuration Steps

​Order Events

Processing

Completed

Failed

​Implementation Example

​Webhook Payload Schema

​Field Descriptions

​Best Practices

​Testing Your Webhook

​Need Help?

Overview

Configuration Steps

Order Events

Implementation Example

Webhook Payload Schema

Field Descriptions

Best Practices

Testing Your Webhook

Need Help?