Build Real-Time Event-Driven Apps with FluxRail: Step-by-Step

Introduction

Modern applications need to react instantly to blockchain events — new transactions, token transfers, contract calls — and take action like updating a database, triggering a payout, or alerting a user. FluxRail's Core product provides real-time blockchain event monitoring with signed webhooks across 31+ chains. In this guide, we'll build a simple event-driven application that monitors a wallet address and logs every incoming USDC transfer, all using plain HTTP calls to the FluxRail API.

Prerequisites

• A FluxRail account (sign up at fluxrail.io)
• An API key — use flux_test_... for sandbox (fully simulated, no real money)
• Basic knowledge of curl or any HTTP client

Step 1: Create a Webhook Endpoint

First, you need a publicly accessible HTTPS URL where FluxRail will send events. For local development, use a tool like ngrok. Your endpoint should accept POST requests and return 200 OK quickly.

Here's a simple Node.js server (no SDK, just plain HTTP) to receive webhooks:

const http = require('http');

http.createServer((req, res) => {
  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    console.log('Received webhook:', body);
    res.writeHead(200);
    res.end('OK');
  });
}).listen(3000, () => console.log('Listening on 3000'));

Step 2: Register a Webhook with FluxRail

Use the POST /api/v1/webhooks endpoint to register your webhook URL and choose which event types to receive. For this tutorial, we'll subscribe to all events for simplicity.

curl -X POST https://api.fluxrail.io/api/v1/webhooks \
  -H "X-API-Key: flux_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-ngrok-url.ngrok.io/webhook",
    "event_types": ["*"]
  }'

The response includes a secret used to verify webhook signatures (HMAC SHA-256) — store it securely.

Step 3: Create a Subscription to Monitor an Address

Now create a subscription for the address you want to monitor. For example, to watch a USDC contract on Ethereum, use the chain slug ethereum and the contract address.

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "type": "contract",
    "webhook_url": "https://your-ngrok-url.ngrok.io/webhook"
  }'

You can also monitor a wallet address by setting type to address and providing the wallet address.

Step 4: Verify Webhook Signature

Every webhook includes an X-FluxRail-Signature header. Verify it using the secret from Step 2 to ensure the request is authentic. Here's a Node.js example:

const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-fluxrail-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Step 5: Handle Incoming Events

Once a transaction occurs, FluxRail sends an event to your webhook. The payload includes details like chain, transaction hash, from/to addresses, amount, and more. Here's a sample event:

{
  "id": "evt_123",
  "type": "transaction.confirmed",
  "chain": "ethereum",
  "data": {
    "hash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "amount": "1000.00",
    "token": "USDC",
    "network": "ERC20"
  },
  "created_at": "2025-04-01T12:00:00Z"
}

Your webhook handler should process the event and return 200 OK. If processing fails, you can retry later using POST /api/v1/events/{id}/retry.

Step 6: Test with Sandbox

FluxRail's sandbox is fully simulated — you can trigger test events without real transactions. Use the POST /api/v1/webhooks/{id}/test endpoint to send a test event to your webhook:

curl -X POST https://api.fluxrail.io/api/v1/webhooks/webhook_123/test \
  -H "X-API-Key: flux_test_xxx"

Step 7: Going Further — Trigger a Payout

Now that you have real-time events, you can automate actions. For example, when a payment is received, you could trigger a payout via FluxRail Pay or Payouts. Here's how to initiate a transfer using the Pay product:

curl -X POST https://api.fluxrail.io/api/v1/transfer \
  -H "X-API-Key: flux_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "network": "ERC20",
    "amount": "10.00",
    "to": "0xRecipientAddress",
    "sponsor_gas": true
  }'

Conclusion

With FluxRail, building real-time, event-driven applications is straightforward. You only need to create a webhook, subscribe to events, and handle them. The same API supports monitoring, transfers, liquidity, and payouts, so you can build complex financial workflows with a single integration. Start with the sandbox, test thoroughly, and then go live with a production key. For more details, check the FluxRail docs.