Partner Callback URLs

Callback URLs (webhooks) are the recommended integration method for tracking transactions. Instead of polling the API, your server receives HTTP POST requests whenever transaction events occur.

Why Use Callback URLs?

Real-Time Updates

Receive notifications instantly when transactions complete, fail, or are refunded

Reduced API Calls

No need to poll for status updates — events are pushed to you

Reliable Delivery

Automatic retries with exponential backoff ensure delivery

Secure

HMAC signatures verify authenticity of every request

Setup

1. Configure Your Endpoint

Configure your webhook URL through the Partner Dashboard at dashboard.nowramp.com under Settings > Webhooks.

2. Save Your Signing Key

When you set a webhook URL, a signing key is generated. Copy it from the Partner Dashboard under Settings > Webhooks.

Store the signing key securely. It’s used to verify webhook authenticity.

3. Implement Your Endpoint

Your endpoint must:

Accept POST requests
Return 2xx status within 30 seconds
Verify the signature (strongly recommended)

Request Format

Every callback includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Timestamp`	Unix timestamp (seconds)
`X-Webhook-Signature`	HMAC-SHA256 signature
`X-Webhook-Event`	Event type (e.g., `transaction.completed`)
`X-Webhook-Delivery-Id`	Unique delivery ID

Payload Structure

{
  "id": "evt_txn_abc123",
  "type": "transaction.completed",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "order": {
      "id": "txn_xyz789",
      "type": "buy",
      "status": "completed",
      "source": {
        "currency": "USD",
        "amount": "100.00"
      },
      "destination": {
        "currency": "ETH",
        "amount": "0.0523",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21"
      },
      "externalOrderId": "gw_order_456",
      "customerId": "cust_uuid",
      "externalCustomerId": "user_123",
      "metadata": {
        "provider": "provider_a",
        "providerOrderId": "gw_order_456",
        "email": "user@example.com",
        "partnerMetadata": {
          "orderId": "your-internal-order-123"
        }
      },
      "createdAt": "2025-01-15T10:25:00.000Z",
      "completedAt": "2025-01-15T10:30:00.000Z"
    }
  }
}

The metadata.partnerMetadata object contains any custom data you passed via session metadata or checkout-intent partnerMetadata. Use it to correlate webhook events back to your internal orders. See the Webhooks guide for details.

Signature Verification

Always verify signatures to ensure requests are from NowRamp.

Algorithm

signature = HMAC-SHA256(
  key: your_signing_key,
  message: "{timestamp}.{json_payload}"
)

Node.js Implementation

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Check timestamp is recent (within 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false;
  }

  const signaturePayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  } catch {
    return false;
  }
}

// Express middleware
app.post('/webhooks/ramp', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(payload);
  processWebhookAsync(event);
  res.status(200).json({ received: true });
});

Python Implementation

import hmac
import hashlib
import time

def verify_webhook_signature(payload: str, signature: str, timestamp: str, secret: str) -> bool:
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    signature_payload = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        signature_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Event Types

Event	Trigger
`transaction.pending`	Checkout created, awaiting payment
`transaction.processing`	Payment received, processing crypto transfer
`transaction.completed`	Crypto delivered to wallet
`transaction.failed`	Transaction failed
`transaction.cancelled`	Transaction cancelled by user or system
`transaction.refunded`	Payment refunded

Example: transaction.completed

{
  "id": "evt_txn_abc123",
  "type": "transaction.completed",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "order": {
      "id": "txn_xyz789",
      "type": "buy",
      "status": "completed",
      "previousStatus": "processing",
      "source": {
        "currency": "USD",
        "amount": "100.00"
      },
      "destination": {
        "currency": "ETH",
        "amount": "0.0523",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21"
      },
      "externalOrderId": "gw_order_456",
      "customerId": "cust_uuid",
      "externalCustomerId": "user_123",
      "metadata": {
        "provider": "provider_a",
        "providerOrderId": "gw_order_456",
        "email": "user@example.com",
        "partnerMetadata": {
          "orderId": "your-internal-order-123"
        }
      },
      "createdAt": "2025-01-15T10:25:00.000Z",
      "completedAt": "2025-01-15T10:30:00.000Z"
    }
  }
}

Example: transaction.failed

{
  "id": "evt_txn_def456",
  "type": "transaction.failed",
  "timestamp": "2025-01-15T10:28:00.000Z",
  "data": {
    "order": {
      "id": "txn_abc789",
      "type": "buy",
      "status": "failed",
      "previousStatus": "processing",
      "source": {
        "currency": "EUR",
        "amount": "50.00"
      },
      "destination": {
        "currency": "USDC",
        "amount": "0",
        "address": "0x123..."
      },
      "externalOrderId": "gw_order_789",
      "customerId": "cust_uuid",
      "externalCustomerId": "user_456",
      "metadata": {
        "provider": "provider_b",
        "providerOrderId": "gw_order_789",
        "partnerMetadata": {
          "orderId": "your-internal-order-456"
        }
      },
      "createdAt": "2025-01-15T10:25:00.000Z"
    }
  }
}

Retry Policy

Failed deliveries are automatically retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	15 minutes
5	1 hour

After 5 failed attempts, the webhook is marked as failed and moved to the dead-letter queue.

Webhook Delivery Management

NowRamp provides partner-facing endpoints to monitor and manage webhook deliveries.

Delivery Statuses

Status	Description
`pending`	Awaiting delivery — queued and will be sent shortly
`delivered`	Successfully delivered — your endpoint returned a 2xx response
`failed`	Delivery failed after retries — moved to dead-letter queue

List Webhook Deliveries

curl "https://api.nowramp.com/v1/webhooks/events?status=failed" \
  -H "X-API-Key: sk_live_your_secret_key"

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `delivered`, `failed`
`eventType`	string	Filter by event type (e.g., `transaction.completed`)
`limit`	number	Results per page (default: 50, max: 100)
`offset`	number	Pagination offset

Retry Failed Delivery

curl -X POST "https://api.nowramp.com/v1/webhooks/events/del_def456/retry" \
  -H "X-API-Key: sk_live_your_secret_key"

You can only retry deliveries with failed status.

Partner Dashboard

You can also manage webhook deliveries from the Partner Dashboard:

View delivery history with filtering
Inspect full payload and response details
Retry failed deliveries with one click
Monitor delivery health and success rates

Best Practices

1. Respond Quickly

Return a 2xx response as fast as possible. Process events asynchronously:

app.post('/webhooks/ramp', (req, res) => {
  res.status(200).json({ received: true });
  queue.add('process-webhook', req.body);
});

2. Handle Duplicates

Events may be delivered more than once. Use the event id for idempotency:

async function processWebhook(event) {
  const existing = await db.webhookEvents.findOne({ eventId: event.id });
  if (existing) return;

  await handleEvent(event);
  await db.webhookEvents.insert({ eventId: event.id, processedAt: new Date() });
}

3. Use HTTPS

Webhook endpoints must use HTTPS in production.

4. Verify Signatures

Always verify the X-Webhook-Signature header.

5. Monitor Failures

Set up alerts for failed webhook deliveries. Use the delivery management API or Partner Dashboard to monitor delivery health.

Testing

Sandbox Events

In sandbox mode, trigger test events:

curl -X POST https://api.sandbox.nowramp.com/v1/webhooks/test \
  -H "X-API-Key: sk_test_your_secret_key" \
  -d '{"eventType": "transaction.completed"}'

Local Development

Use ngrok or similar to expose your local server:

ngrok http 3000
# Use the https URL as your webhook URL

Troubleshooting

Issue	Solution
No webhooks received	Check webhook URL is set in project settings
Signature invalid	Verify using raw request body, check signing key
Events delayed	Check your endpoint returns 2xx quickly
Missing events	Check dead-letter queue for failed deliveries

Getting Started

Guides

Resources

Partner Callback URLs

Partner Callback URLs

Why Use Callback URLs?

Real-Time Updates

Reduced API Calls

Reliable Delivery

Secure

Setup

1. Configure Your Endpoint

2. Save Your Signing Key

3. Implement Your Endpoint

Request Format

Payload Structure

Signature Verification

Algorithm

Node.js Implementation

Python Implementation

Event Types

Example: transaction.completed

Example: transaction.failed

Retry Policy

Webhook Delivery Management

Delivery Statuses

List Webhook Deliveries

Retry Failed Delivery

Partner Dashboard

Best Practices

1. Respond Quickly

2. Handle Duplicates

3. Use HTTPS

4. Verify Signatures

5. Monitor Failures

Testing

Sandbox Events

Local Development

Troubleshooting

​Partner Callback URLs

​Why Use Callback URLs?

Real-Time Updates

Reduced API Calls

Reliable Delivery

Secure

​Setup

​1. Configure Your Endpoint

​2. Save Your Signing Key

​3. Implement Your Endpoint

​Request Format

​Payload Structure

​Signature Verification

​Algorithm

​Node.js Implementation

​Python Implementation

​Event Types

​Example: transaction.completed

​Example: transaction.failed

​Retry Policy

​Webhook Delivery Management

​Delivery Statuses

​List Webhook Deliveries

​Retry Failed Delivery

​Partner Dashboard

​Best Practices

​1. Respond Quickly

​2. Handle Duplicates

​3. Use HTTPS

​4. Verify Signatures

​5. Monitor Failures

​Testing

​Sandbox Events

​Local Development

​Troubleshooting

Partner Callback URLs

Why Use Callback URLs?

Setup

1. Configure Your Endpoint

2. Save Your Signing Key

3. Implement Your Endpoint

Request Format

Payload Structure

Signature Verification

Algorithm

Node.js Implementation

Python Implementation

Event Types

Example: transaction.completed

Example: transaction.failed

Retry Policy

Webhook Delivery Management

Delivery Statuses

List Webhook Deliveries

Retry Failed Delivery

Partner Dashboard

Best Practices

1. Respond Quickly

2. Handle Duplicates

3. Use HTTPS

4. Verify Signatures

5. Monitor Failures

Testing

Sandbox Events

Local Development

Troubleshooting