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

Each event carries an eventType and the current orderStatus in its payload. Ramp-order events use the ramp_order.status_change type. The concrete status is always in the orderStatus field of the payload — not in the event name.

Order status semantics

The concrete status is in payload.orderStatus. The Webhook column shows which statuses are pushed to your endpoint — the rest are observable only by polling GET /ext/ramp_order/{uid}.

Status	Meaning	Terminal?	Webhook
`created`	Order created, awaiting payment / start of processing.	No	Yes
`processing`	Payment received; crypto being settled on-chain to the user.	No	Yes
`completed`	Crypto delivered to the destination wallet. Success — immutable once reached.	Yes	Yes
`failed`	A settlement attempt failed. Not terminal — Rampnow re-settles the order, so it can still move to `processing` → `completed`. Treat as “in-flight, needs retry,” not a final failure.	No	Yes
`payment_failed`	The user’s fiat/card payment failed or was declined. Terminal — the user must create a new order to retry; the same order does not move back to `processing`.	Yes	Yes
`expired`	Order not paid within its validity window.	Yes	Yes
`canceled`	Order canceled.	Yes	Yes
`blocked`	Transaction blocked by KYT (on-chain risk screening); also the state for a refunded order (you will see `paymentStatus: refunded`).	Yes	Yes
`payment_processing`	Async fiat payment authorizing/clearing. Internal transition — no webhook; poll if you need it.	No	No

failed is not final. Do not close or refund on your side when you receive failed — Rampnow retries and re-settles. Wait for completed, or poll the order.

Every terminal state now emits a webhook — including expired, canceled and blocked — so you no longer need to poll to observe a terminal failure. completed is immutable once reached.

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)

Acknowledge receipt by returning any 2xx status (200–299). The response body is ignored — an empty body is fine, and it does not need to be JSON. Any non-2xx response, or a connection/timeout error, is treated as a failed delivery and retried (see Delivery & retries).

Delivery and retries

Success is determined solely by the HTTP status code: any 2xx marks the event delivered. The response body, content type, and length are ignored.
Failure is any non-2xx status or a transport error (connection refused, DNS, TLS, timeout).
Retries: a failed event is retried up to 10 times with exponential backoff, spanning roughly 24 hours in total. Delivery is idempotent per event — the same eventUid is reused across retries, so de-duplicate on eventUid.
No auto-disable: repeated failures never disable your endpoint. After the retry budget is exhausted the event stays in a failed state and can be re-sent manually from the Partner Dashboard.
Because a completed order’s webhook carries the final dstFillAmount, transactionHash, and walletAddress, a short outage on your side will not lose those values — they arrive on the next successful retry.

Signature Verification

Every webhook is signed so you can verify it originated from Rampnow. Reject any request whose signature does not match.

Header	Description
`X-RAMPNOW-SIGN`	Hex-encoded HMAC-SHA256 signature of the request
`X-RAMPNOW-TIMESTAMP`	Unix timestamp (seconds) used in the signed message

Algorithm: HMAC-SHA256, hex-encoded. Signing secret: your API secret — the same secret you use to sign outbound API calls (from the API Hub in the Partner Dashboard). There is no separate webhook secret. Signed message — the concatenation, in this exact order:

message = timestamp + "POST" + path + rawBody

timestamp — the value of the X-RAMPNOW-TIMESTAMP header.
path — the path (and query string, if any) of the webhook URL you registered, e.g. /rampnow/webhook.
rawBody — the exact raw request body bytes, verified before any JSON re-serialization.

const crypto = require("crypto");

// webhookPath is the path (+ query) of the URL you registered with Rampnow
function verifyRampnowWebhook(req, apiSecret, webhookPath) {
  const timestamp = req.header("X-RAMPNOW-TIMESTAMP");
  const signature = req.header("X-RAMPNOW-SIGN");
  const rawBody = req.rawBody; // raw bytes, not JSON.stringify(req.body)

  const message = timestamp + "POST" + webhookPath + rawBody;
  const expected = crypto
    .createHmac("sha256", apiSecret)
    .update(message)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

import hmac, hashlib

# webhook_path is the path (+ query) of the URL you registered with Rampnow
def verify_rampnow_webhook(headers, raw_body: bytes, api_secret: str, webhook_path: str) -> bool:
    timestamp = headers["X-RAMPNOW-TIMESTAMP"]
    signature = headers["X-RAMPNOW-SIGN"]

    message = timestamp + "POST" + webhook_path + raw_body.decode("utf-8")
    expected = hmac.new(api_secret.encode(), message.encode(), hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Capture the raw request body for verification. Frameworks that parse and re-serialize JSON can reorder keys or change whitespace, which changes the bytes and breaks the signature.

Webhook Payload Schema

The webhook payload for On/Off Ramp Orders is shown below.

{
  "createdAt": "2024-10-01T12:00:00Z",
  "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
  "eventType": "ramp_order.status_change",
  "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": "received",
    "paymentMode": "card",
    "srcCurrency": "USD",
    "srcChain": "fiat",
    "srcAmount": 100,
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "dstAmount": 0.3,
    "dstFillAmount": 0.2997,
    "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
    "transactionHash": [
      "Ox235ebf73d0E20db0A72509207599C816510e11C9535ebf73d0E20db0A72509207599C816510e11C9"
    ],
    "feeDetails": [
      { "type": "platform", "fee": 1.0, "currency": "USD", "isInclusive": false },
      { "type": "network", "fee": 0.8, "currency": "USD", "isInclusive": false },
      { "type": "partner", "fee": 1.5, "currency": "USD", "isInclusive": false }
    ],
    "partnerFee": 1.5,
    "partnerCurrency": "USDC"
  }
}

Field Descriptions

Field	Type	Description
`createdAt`	string	Webhook event creation timestamp (ISO 8601)
`eventUid`	string	Unique webhook event identifier
`eventType`	string	Event type: `ramp_order.status_change`. The concrete status is in `payload.orderStatus`.
`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 order status. See the status table above for all values, their meaning, and which ones are pushed as webhooks.
`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	Quoted amount in destination currency, fixed at order creation.
`dstFillAmount`	number	Actual amount delivered on-chain to the recipient. Set once the order reaches `completed`; `0` before then. Use this (not `dstAmount`) for reconciliation — the difference from `dstAmount` on an onramp is the on-chain network/gas fee.
`walletAddress`	string	Recipient wallet address (the final recipient the crypto was sent to)
`walletAddressTag`	string	Optional wallet tag/memo
`transactionHash`	array	Blockchain transaction hash(es), set when the order completes
`feeDetails`	array	Fee breakdown; each entry has `type`, `fee`, `currency` (in `srcCurrency`). See feeDetails types.
`partnerFee`	number	Your partner fee / markup for the order
`partnerCurrency`	string	Currency of `partnerFee` — always `USDC` (the USDC-equivalent partner fee)

Best Practices

Security

Use HTTPS endpoints only
Always verify the X-RAMPNOW-SIGN signature (see Signature Verification) and reject requests that fail
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

Configuration

Webhooks

Overview

Configuration Steps

Order Events

Order status semantics

Implementation Example

Delivery and retries

Signature Verification

Webhook Payload Schema

Field Descriptions

Best Practices

Testing Your Webhook

Need Help?

​Overview

​Configuration Steps

​Order Events

​Order status semantics

​Implementation Example

​Delivery and retries

​Signature Verification

​Webhook Payload Schema

​Field Descriptions

​Best Practices

​Testing Your Webhook

​Need Help?

Overview

Configuration Steps

Order Events

Order status semantics

Implementation Example

Delivery and retries

Signature Verification

Webhook Payload Schema

Field Descriptions

Best Practices

Testing Your Webhook

Need Help?