Webhooks

Overview

Chainrails webhooks allow you to receive real-time notifications for both cross-chain intents and ramp orders. Instead of polling the API for status updates, webhooks push event data to your server when significant state changes occur.

Quick Start

1. Create a Webhook

You’d rarely need to do this manually, as you can create webhooks directly from the Dashboard. But if you want to create one programmatically, here’s how:

curl -X POST https://api.chainrails.io/api/v1/client/webhooks \
  -H "Authorization: Bearer CLIENT_JWT_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/chainrails",
    "events": [
      "intent.funded",
      "intent.completed",
      "ramp.order.initiated",
      "ramp.order.completed"
    ],
    "environment": "live",
    "is_active": true
  }'

Response:

{
  "webhook_id": "wh_abc123...",
  "client_id": "client_xyz...",
  "url": "https://api.example.com/webhooks/chainrails",
  "events": [
    "intent.funded",
    "intent.completed",
    "ramp.order.initiated",
    "ramp.order.completed"
  ],
  "is_active": true,
  "environment": "live",
  "secret": "whsec_1234567890abcdef...",
  "created_at": "2025-12-07T10:00:00Z",
  "updated_at": "2025-12-07T10:00:00Z"
}

⚠️ Important: Save the secret value - it’s only returned once when creating or regenerating the webhook. You’ll need it to verify webhook signatures.

2. Implement Your Webhook Endpoint

Your webhook endpoint must:

Accept POST requests
Respond with 200 OK within 5 seconds
Verify the signature (instructions below)
Be publicly accessible (HTTPS required for live webhooks)

For local testing, you can use tools like ngrok to expose your local server to the internet.

Event Types

Subscribe to the events relevant to your use case:

Intent Events

Event Type	Description	When It’s Triggered
`intent.created`	Intent was created	When a new intent is created
`intent.funded`	User funded the intent address	When tokens are detected on the intent address
`intent.initiated`	Bridge transaction started	When Chainrails initiates the bridge transaction
`intent.completed`	Transfer successfully completed	When tokens arrive on destination chain
`intent.expired`	Intent expired without funding	When intent funding deadline passes
`intent.refunded`	Funds returned to sender	When transfer fails and funds are refunded

Ramp Order Events

Event Type	Description	When It’s Triggered
`ramp.order.initiated`	Ramp order started	When a ramp order is initiated with a provider
`ramp.order.funded`	User funding confirmed	When payment is received for the ramp order
`ramp.order.completed`	Ramp order completed	When the ramp flow settles successfully
`ramp.order.failed`	Ramp order failed	When the provider reports payment failure
`ramp.order.expired`	Ramp order expired	When the ramp payment window expires
`ramp.order.cancelled`	Ramp order cancelled	When the order is cancelled before completion

Ramp webhooks expose a provider-agnostic lifecycle. Provider-specific intermediate statuses are normalized into the event set above.

Webhook Payload Structure

All webhook events follow this structure:

{
  "id": "evt_1234567890abcdef", 
  "type": "intent.completed",
  "created_at": "2025-12-07T10:30:00Z",
  "data": {
    "intent_id": 12345,
    "intent_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "source_chain": "ARBITRUM_MAINNET",
    "destination_chain": "BASE_MAINNET",
    "status": "COMPLETED",
    "tx_hash": "0xabc123...",
    "sender": "0x1234...",
    "recipient": "0x5678...",
    "amount": "1000000",
    "token_in": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "token_out": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "metadata": {
      "custom_field": "value"
    }
  },
  "previous_attributes": { 
    "status": "INITIATED"
  }
}

Ramp Event Example

Ramp events follow the same top-level shape, but with ramp order fields in data:

{
  "id": "evt_1234567890abcdef",
  "type": "ramp.order.completed",
  "created_at": "2025-12-07T10:30:00Z",
  "data": {
    "ramp_order_id": 987,
    "order_ref": "cr_ramp_01JABC...",
    "ramp_direction": "on-ramp",
    "ramp_status": "COMPLETED",
    "fiat_currency": "NGN",
    "fiat_amount": "15000",
    "crypto_amount": "10",
    "crypto_currency": "USDC",
    "payment_channel": "bank_transfer",
    "ramp_provider": "FONBNK",
    "intent_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}

Field Descriptions

id: Unique identifier for this webhook event (idempotency key)
type: One of the event types
created_at: When the event occurred (UTC, ISO 8601)
data: Event-specific payload (intent fields for intent events, ramp fields for ramp events)
previous_attributes: What changed (only for update events)

Ramp Data Fields

ramp_order_id: Internal ramp order ID
order_ref: Client-facing order reference
ramp_direction: on-ramp or off-ramp
ramp_status: Current normalized ramp status
fiat_currency: Fiat currency code (ISO 4217)
fiat_amount: Fiat amount for the order
crypto_amount: Crypto amount involved in the order
crypto_currency: Crypto asset symbol (for example USDC)
payment_channel: Payment channel used by the provider
ramp_provider: Provider handling the order
intent_address: Linked intent address (when available)

Security & Signature Verification

All webhook payloads are signed using HMAC-SHA256. Always verify signatures to ensure the webhook came from Chainrails.

How Signing Works

Chainrails generates a signature using your webhook secret
Signature is sent in the X-Chainrails-Signature header
Timestamp is sent in the X-Chainrails-Timestamp header
You verify the signature matches what you compute

Signature Format

The signature is computed as:

HMAC-SHA256(secret, timestamp + "." + request_body)

Verification Example (Node.js)

import { createHmac } from 'crypto';

function verifyWebhookSignature(
  payload: string, 
  signature: string, 
  timestamp: string,
  secret: string 
): boolean {
  // Check timestamp to prevent replay attacks (max 5 minutes old)
  const eventTime = parseInt(timestamp, 10) * 1000;
  const currentTime = Date.now();
  const timeDiff = Math.abs(currentTime - eventTime);
  
  if (timeDiff > 5 * 60 * 1000) {
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Compare signatures (constant-time comparison recommended)
  return signature === expectedSignature;
}

Delivery & Retries

Delivery Behavior

Timeout: Webhooks must respond within 5 seconds
Success: Any 2xx status code (200, 201, 204, etc.)
Failure: Timeouts, network errors, or non-2xx responses
Retries: Automatic retry with exponential backoff

Retry Schedule

Failed deliveries are automatically retried:

Attempt	Delay After Failure
1	Immediate
2	1 minute
3	5 minutes
4	15 minutes
5	1 hour
6	6 hours
7	24 hours

After 7 attempts, the delivery is marked as permanently failed.

Sample Implementation

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

  // Verify signature
  const isValid = verifyWebhookSignature(
    rawBody,
    signature,
    timestamp,
    process.env.CHAINRAILS_WEBHOOK_SECRET
  );

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Parse and process the event
  const event = JSON.parse(rawBody);
  console.log('Received event:', event.type);

  // Handle the event
  handleWebhookEvent(event);

  // Always respond with 200 OK
  res.status(200).json({ received: true });
});

Introduction

Concepts

Developer Guides

Essentials

Overview

Quick Start

1. Create a Webhook

2. Implement Your Webhook Endpoint

Event Types

Intent Events

Ramp Order Events

Webhook Payload Structure

Ramp Event Example

Field Descriptions

Ramp Data Fields

Security & Signature Verification

How Signing Works

Signature Format

Verification Example (Node.js)

Delivery & Retries

Delivery Behavior

Retry Schedule

Sample Implementation

​Overview

​Quick Start

​1. Create a Webhook

​2. Implement Your Webhook Endpoint

​Event Types

​Intent Events

​Ramp Order Events

​Webhook Payload Structure

​Ramp Event Example

​Field Descriptions

​Ramp Data Fields

​Security & Signature Verification

​How Signing Works

​Signature Format

​Verification Example (Node.js)

​Delivery & Retries

​Delivery Behavior

​Retry Schedule

​Sample Implementation

Overview

Quick Start

1. Create a Webhook

2. Implement Your Webhook Endpoint

Event Types

Intent Events

Ramp Order Events

Webhook Payload Structure

Ramp Event Example

Field Descriptions

Ramp Data Fields

Security & Signature Verification

How Signing Works

Signature Format

Verification Example (Node.js)

Delivery & Retries

Delivery Behavior

Retry Schedule

Sample Implementation