Webhook Configuration

Webhooks are optional but recommended. They are the fastest way to learn that an order changed status.

Overview

Rampnow sends a POST request to your webhook endpoint each time an order’s status changes. Configure the endpoint in your Rampnow Partner Dashboard.

Configuration steps

Access API Hub

Navigate to the API Hub in your Rampnow Partner Dashboard.

Add webhook URL

Enter the HTTPS endpoint on your server that will receive webhook notifications.

All webhooks are delivered to this account-level URL. The webhookUrl field on Create Order is not currently used as a delivery target, so don’t rely on it.

Select event types

Subscribe to ramp_order.status_change. Rampnow only sends events you are subscribed to.

Order events

Every event has eventType: "ramp_order.status_change". The order’s status is in payload.orderStatus, not in the event name. A webhook is sent when the order status changes. These do not produce a webhook:

unknown (the order was created but the customer hasn’t confirmed it yet)
payment_processing
changes to paymentStatus alone

The meaning of every status, which ones are final and what to do in each is on Order Status.

failed is not final. Don’t close or refund the order on your side when you receive failed. The Rampnow operations team either retries it (it moves back to processing) or blocks and refunds it. Wait for the next webhook.

Delivery and retries

Success is any 2xx response. The response body, content type and length are ignored, so an empty body is fine.
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 (6 minutes, doubling, then every 6 hours), spanning roughly 24 hours in total.
No auto-disable: repeated failures never disable your endpoint. After the retries run out, the event stays failed and you can re-send it from the Partner Dashboard.
Each attempt re-reads the order, so a retry after an outage still carries the final dstFillAmount, transactionHash and walletAddress.

Return 2xx as soon as you have verified and stored the event, then process it asynchronously. Slow handlers risk timeouts and duplicate deliveries.

Idempotency

De-duplicate on eventUid. It is generated once per status change and reused on every retry of that event. orderUid is not a de-duplication key: one order produces several events. Because each event carries the order’s status at the time it was sent, two quick changes can arrive as two events with the same status, and events can arrive out of order. Store the latest status per order and ignore any event whose payload.updateTime is older than the one you already have.

Signature verification

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

Header	Description
`X-RAMPNOW-SIGN`	Hex-encoded HMAC-SHA256 signature (lowercase)
`X-RAMPNOW-TIMESTAMP`	Unix timestamp in seconds when this attempt was sent

Signing secret: your API secret, the same secret you use to sign API requests (from the API Hub in the Partner Dashboard). There is no separate webhook secret. Signed message: the concatenation, in this exact order, with no separators:

message = timestamp + "POST" + path + rawBody

timestamp: the value of the X-RAMPNOW-TIMESTAMP header.
path: the path, plus the query string if any, of the webhook URL configured in API Hub, for example /rampnow/webhook. Use the configured value as a constant. Don’t read it from the incoming request: a proxy or load balancer may rewrite the path.
rawBody: the exact bytes of the request body, before any JSON parsing.

Test vector

Use these fixed inputs to check your verification code before you go live. If your code computes the same signature, it builds the message correctly. The body is the Buy · created example below, exactly as Rampnow sends it on the wire: compact JSON, with no spaces or line breaks.

Input	Value
API secret	`test-secret-key`
`X-RAMPNOW-TIMESTAMP`	`1772080882`
Webhook path	`/rampnow/webhook`
Body	The single line below

Body:

{"createdAt":"2026-10-01T12:00:02Z","eventUid":"853d470c-db91-4c6e-9724-acfccd138306","eventType":"ramp_order.status_change","payload":{"orderUid":"5de57551-3272-4af5-86a4-5eeae6ccc37f","createTime":"2026-10-01T11:58:40Z","updateTime":"2026-10-01T12:00:00Z","externalOrderUid":"your-order-1001","orderType":"buy","orderStatus":"created","paymentStatus":"created","paymentMode":"card","srcCurrency":"EUR","srcChain":"fiat","srcAmount":"250","dstCurrency":"ETH","dstChain":"ethereum","dstAmount":"0.0812","dstFillAmount":"0","walletAddress":"0x535ebf73d0E20db0A72509207599C816510e11C9","walletAddressTag":"","feeDetails":[{"type":"platform","fee":"4.5","currency":"EUR","isInclusive":true},{"type":"network","fee":"0.8","currency":"EUR","isInclusive":true},{"type":"partner","fee":"2.5","currency":"EUR","isInclusive":true}],"partnerFee":"2.71","partnerCurrency":"USDC","cryptoAccountDetail":{"custodyType":"unhosted","address":"0x535ebf73d0E20db0A72509207599C816510e11C9"}}}

Message to sign: 1772080882 + POST + /rampnow/webhook + the body above, with no separators. Expected X-RAMPNOW-SIGN:

79ae56d41cc58a6bf20b45405eec78115944831dcd2f37a061a30754b4aead9f

The test timestamp is in the past, so a full verification would reject it under the replay window. Check the signature on its own with the rampnowSignature / rampnow_signature helper in the examples below.

Replay window

Rampnow signs every delivery attempt, including retries, with a fresh timestamp. A legitimate request is therefore never old. Reject any request whose timestamp is more than 5 minutes (300 seconds) away from your server’s clock, and keep your clock in sync with NTP. Together with eventUid de-duplication, this stops replayed requests.

Examples

const crypto = require("crypto");
const express = require("express");

const API_SECRET = process.env.RAMPNOW_API_SECRET;
// Path (and query, if any) of the webhook URL configured in API Hub
const WEBHOOK_PATH = "/rampnow/webhook";
const TOLERANCE_SECONDS = 300;

// Test vector: with API_SECRET = "test-secret-key",
//   rampnowSignature("1772080882", Buffer.from(<test vector body>)).toString("hex")
// must return 79ae56d41cc58a6bf20b45405eec78115944831dcd2f37a061a30754b4aead9f
function rampnowSignature(timestamp, rawBody) {
  return crypto
    .createHmac("sha256", API_SECRET)
    .update(timestamp + "POST" + WEBHOOK_PATH)
    .update(rawBody)
    .digest();
}

function verifyRampnowWebhook(timestamp, signature, rawBody) {
  if (!/^\d+$/.test(timestamp)) return false;
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > TOLERANCE_SECONDS) return false;

  signature = signature.toLowerCase();
  if (!/^[0-9a-f]{64}$/.test(signature)) return false;

  // Both buffers are 32 bytes here, so timingSafeEqual cannot throw
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    rampnowSignature(timestamp, rawBody)
  );
}

const app = express();

// express.raw keeps the body as a Buffer: don't use express.json() on this route
app.post(WEBHOOK_PATH, express.raw({ type: "*/*" }), (req, res) => {
  const ok = verifyRampnowWebhook(
    req.get("X-RAMPNOW-TIMESTAMP") || "",
    req.get("X-RAMPNOW-SIGN") || "",
    req.body
  );
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // De-duplicate on event.eventUid, store it, then process asynchronously
  res.sendStatus(200);
});

app.listen(3000);

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

API_SECRET = os.environ["RAMPNOW_API_SECRET"].encode()
# Path (and query, if any) of the webhook URL configured in API Hub
WEBHOOK_PATH = "/rampnow/webhook"
TOLERANCE_SECONDS = 300

app = Flask(__name__)


# Test vector: with API_SECRET = b"test-secret-key",
#   rampnow_signature("1772080882", <test vector body as bytes>)
# must return "79ae56d41cc58a6bf20b45405eec78115944831dcd2f37a061a30754b4aead9f"
def rampnow_signature(timestamp: str, raw_body: bytes) -> str:
    message = timestamp.encode() + b"POST" + WEBHOOK_PATH.encode() + raw_body
    return hmac.new(API_SECRET, message, hashlib.sha256).hexdigest()


def verify_rampnow_webhook(timestamp: str, signature: str, raw_body: bytes) -> bool:
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = rampnow_signature(timestamp, raw_body)
    return hmac.compare_digest(signature.lower().encode(), expected.encode())


@app.post(WEBHOOK_PATH)
def rampnow_webhook():
    raw_body = request.get_data()  # raw bytes, read before any JSON parsing
    if not verify_rampnow_webhook(
        request.headers.get("X-RAMPNOW-TIMESTAMP", ""),
        request.headers.get("X-RAMPNOW-SIGN", ""),
        raw_body,
    ):
        abort(401)

    event = json.loads(raw_body)
    # De-duplicate on event["eventUid"], store it, then process asynchronously
    return "", 200


if __name__ == "__main__":
    app.run(port=3000)

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

Payload

Each request body is an envelope with the order data in payload:

Field	Type	Description
`eventUid`	string	Unique event id, stable across retries. De-duplicate on this
`eventType`	string	`ramp_order.status_change`
`createdAt`	string	Event envelope timestamp. Use `payload.updateTime` for ordering instead
`payload`	object	The order, described below

Payload examples

{
  "createdAt": "2026-10-01T12:00:02Z",
  "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
  "eventType": "ramp_order.status_change",
  "payload": {
    "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
    "createTime": "2026-10-01T11:58:40Z",
    "updateTime": "2026-10-01T12:00:00Z",
    "externalOrderUid": "your-order-1001",
    "orderType": "buy",
    "orderStatus": "created",
    "paymentStatus": "created",
    "paymentMode": "card",
    "srcCurrency": "EUR",
    "srcChain": "fiat",
    "srcAmount": "250",
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "dstAmount": "0.0812",
    "dstFillAmount": "0",
    "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
    "walletAddressTag": "",
    "feeDetails": [
      { "type": "platform", "fee": "4.5", "currency": "EUR", "isInclusive": true },
      { "type": "network", "fee": "0.8", "currency": "EUR", "isInclusive": true },
      { "type": "partner", "fee": "2.5", "currency": "EUR", "isInclusive": true }
    ],
    "partnerFee": "2.71",
    "partnerCurrency": "USDC",
    "cryptoAccountDetail": {
      "custodyType": "unhosted",
      "address": "0x535ebf73d0E20db0A72509207599C816510e11C9"
    }
  }
}

{
  "createdAt": "2026-10-01T12:04:11Z",
  "eventUid": "1b0f6a9e-41c2-4f0e-9d0a-7f3a2c6e9b41",
  "eventType": "ramp_order.status_change",
  "payload": {
    "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
    "createTime": "2026-10-01T11:58:40Z",
    "updateTime": "2026-10-01T12:04:09Z",
    "externalOrderUid": "your-order-1001",
    "orderType": "buy",
    "orderStatus": "completed",
    "paymentStatus": "accepted",
    "paymentMode": "card",
    "srcCurrency": "EUR",
    "srcChain": "fiat",
    "srcAmount": "250",
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "dstAmount": "0.0812",
    "dstFillAmount": "0.0809",
    "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
    "walletAddressTag": "",
    "transactionHash": [
      "0x9c1e5b7f3a2d4e6c8b0a1f2e3d4c5b6a7980f1e2d3c4b5a69788f7e6d5c4b3a2"
    ],
    "feeDetails": [
      { "type": "platform", "fee": "4.5", "currency": "EUR", "isInclusive": true },
      { "type": "network", "fee": "0.8", "currency": "EUR", "isInclusive": true },
      { "type": "partner", "fee": "2.5", "currency": "EUR", "isInclusive": true }
    ],
    "partnerFee": "2.71",
    "partnerCurrency": "USDC",
    "cryptoAccountDetail": {
      "custodyType": "unhosted",
      "address": "0x535ebf73d0E20db0A72509207599C816510e11C9"
    }
  }
}

{
  "createdAt": "2026-10-01T12:01:30Z",
  "eventUid": "e3a7d2c1-9b8f-4a6e-8d5c-2b1a0f9e8d7c",
  "eventType": "ramp_order.status_change",
  "payload": {
    "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
    "createTime": "2026-10-01T11:58:40Z",
    "updateTime": "2026-10-01T12:01:28Z",
    "externalOrderUid": "your-order-1001",
    "orderType": "buy",
    "orderStatus": "payment_failed",
    "paymentStatus": "rejected",
    "paymentMode": "card",
    "srcCurrency": "EUR",
    "srcChain": "fiat",
    "srcAmount": "250",
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "dstAmount": "0.0812",
    "dstFillAmount": "0",
    "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
    "walletAddressTag": "",
    "feeDetails": [
      { "type": "platform", "fee": "4.5", "currency": "EUR", "isInclusive": true },
      { "type": "network", "fee": "0.8", "currency": "EUR", "isInclusive": true },
      { "type": "partner", "fee": "2.5", "currency": "EUR", "isInclusive": true }
    ],
    "partnerFee": "2.71",
    "partnerCurrency": "USDC"
  }
}

{
  "createdAt": "2026-10-01T14:22:05Z",
  "eventUid": "4f6c2a1b-8e9d-4c3b-a2f1-0e9d8c7b6a54",
  "eventType": "ramp_order.status_change",
  "payload": {
    "orderUid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "createTime": "2026-10-01T14:05:12Z",
    "updateTime": "2026-10-01T14:22:03Z",
    "externalOrderUid": "your-order-2001",
    "orderType": "sell",
    "orderStatus": "processing",
    "paymentStatus": "accepted",
    "paymentMode": "crypto",
    "srcCurrency": "USDT",
    "srcChain": "ethereum",
    "srcAmount": "500",
    "dstCurrency": "EUR",
    "dstChain": "fiat",
    "dstAmount": "452.10",
    "dstFillAmount": "0",
    "walletAddress": "DE89370400440532013000",
    "walletAddressTag": "",
    "feeDetails": [
      { "type": "platform", "fee": "5", "currency": "USDT", "isInclusive": true },
      { "type": "network", "fee": "1.2", "currency": "USDT", "isInclusive": true },
      { "type": "partner", "fee": "5", "currency": "USDT", "isInclusive": true }
    ],
    "partnerFee": "5",
    "partnerCurrency": "USDC",
    "bankAccountDetail": {
      "name": "John Doe",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "currency": "EUR",
      "country": "DE"
    }
  }
}

{
  "createdAt": "2026-10-01T14:40:51Z",
  "eventUid": "7d6c5b4a-3e2f-4d1c-8b0a-9f8e7d6c5b4a",
  "eventType": "ramp_order.status_change",
  "payload": {
    "orderUid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "createTime": "2026-10-01T14:05:12Z",
    "updateTime": "2026-10-01T14:40:49Z",
    "externalOrderUid": "your-order-2001",
    "orderType": "sell",
    "orderStatus": "completed",
    "paymentStatus": "accepted",
    "paymentMode": "crypto",
    "srcCurrency": "USDT",
    "srcChain": "ethereum",
    "srcAmount": "500",
    "dstCurrency": "EUR",
    "dstChain": "fiat",
    "dstAmount": "452.10",
    "dstFillAmount": "452.10",
    "walletAddress": "DE89370400440532013000",
    "walletAddressTag": "",
    "transactionHash": [
      "SEPA-REF-20261001-8F3K2"
    ],
    "feeDetails": [
      { "type": "platform", "fee": "5", "currency": "USDT", "isInclusive": true },
      { "type": "network", "fee": "1.2", "currency": "USDT", "isInclusive": true },
      { "type": "partner", "fee": "5", "currency": "USDT", "isInclusive": true }
    ],
    "partnerFee": "5",
    "partnerCurrency": "USDC",
    "bankAccountDetail": {
      "name": "John Doe",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "currency": "EUR",
      "country": "DE"
    }
  }
}

Payload fields

All amounts are decimal strings (for example "0.0809"). Parse them with a decimal type, not a float.

Field	Type	Description
`orderUid`	string	Rampnow’s order id
`externalOrderUid`	string	Your order id, as sent on Create Order
`createTime`	string	Order creation time (ISO 8601, UTC)
`updateTime`	string	Time of this status change (ISO 8601, UTC). Use it to order events
`orderType`	string	`buy` or `sell`
`orderStatus`	string	Current order status. See Order Status
`paymentStatus`	string	Current payment status. See Payment statuses
`paymentMode`	string	Payment method used (for example `card`, `sepa`, `crypto` for a sell deposit)
`srcCurrency` / `srcChain`	string	Source currency and chain (`fiat` for a fiat leg)
`srcAmount`	string	Amount in the source currency
`dstCurrency` / `dstChain`	string	Destination currency and chain (`fiat` for a fiat leg)
`dstAmount`	string	Quoted destination amount
`dstFillAmount`	string	Actual amount delivered (buy: crypto sent on-chain; sell: fiat paid out). `"0"` until `completed`. Reconcile on this, not `dstAmount`
`walletAddress`	string	Destination: the crypto address (buy), or the IBAN / account number (sell)
`walletAddressTag`	string	Memo/tag for chains that need one (XRP, XLM, TON, …). Empty otherwise
`cryptoAccountDetail`	object	Destination crypto account (`address`, `custodyType`). Buy orders
`bankAccountDetail`	object	Destination bank account (`name`, `iban` or `accountNumber`, `bic`, `country`, `currency`, …). Sell orders
`transactionHash`	string[]	Buy: on-chain transaction hash(es) of the delivery. Sell: the payout provider’s reference. Left out of the payload until set
`feeDetails`	array	Fee breakdown; each entry has `type`, `fee` (string), `currency`, `isInclusive`. See feeDetails types
`partnerFee`	string	Your partner fee for the order, in `partnerCurrency`
`partnerCurrency`	string	Currency of `partnerFee`: always `USDC`

Best practices

Security

Use an HTTPS endpoint
Verify X-RAMPNOW-SIGN on every request and reject failures with 401
Reject timestamps more than 5 minutes from your clock
Log incoming webhooks (without your secret) for debugging

Reliability

Return 2xx quickly and process asynchronously
De-duplicate on eventUid
Apply events by payload.updateTime and ignore older ones
Poll Get Order as a fallback if an expected webhook doesn’t arrive

Error handling

Respond non-2xx only when you want Rampnow to retry
Re-send failed events from the Partner Dashboard after an outage longer than 24 hours
Contact support if webhooks stop arriving

Testing your webhook

Run your endpoint locally

Start your webhook server, for example on port 3000.

Check your signature code

Run your verification code against the test vector and confirm it produces the expected signature.

Expose it with a tunnel

Use a tool like ngrok to get a public HTTPS URL:

ngrok http 3000

Add the tunnel URL

Add the tunnel URL, including your webhook path, in the API Hub of your sandbox Partner Dashboard.

Create a test order

Create a sandbox order and check that your endpoint receives and verifies the webhook. Sandbox Testing shows how to drive each status.

Need help?

If webhooks aren’t arriving or you have questions about the payload, contact [email protected].

Build with AI

Learn about Rampnow

What's Supported

Integrations

Help

Overview

Configuration steps

Order events

Delivery and retries

Idempotency

Signature verification

Test vector

Replay window

Examples

Payload

Payload examples

Payload fields

Best practices

Testing your webhook

Need help?

​Overview

​Configuration steps

​Order events

​Delivery and retries

​Idempotency

​Signature verification

​Test vector

​Replay window

​Examples

​Payload

​Payload examples

​Payload fields

​Best practices

​Testing your webhook

​Need help?

Overview

Configuration steps

Order events

Delivery and retries

Idempotency

Signature verification

Test vector

Replay window

Examples

Payload

Payload examples

Payload fields

Best practices

Testing your webhook

Need help?