Building Real-Time Event-Driven Applications with FluxRail

Why Event-Driven Architecture Needs Reliable Blockchain Monitoring

In modern Web3 applications, reacting to on-chain events in real time is critical. Whether you're crediting a user's deposit, triggering a payout, or updating a dashboard, you need to know the moment a transaction hits the blockchain. But polling nodes across multiple chains is expensive, error-prone, and slow. FluxRail's Core product solves this with a unified API that monitors addresses and contracts across 31+ chains and delivers signed webhooks to your backend.

This guide walks you through building a real-time event-driven application using FluxRail. We'll cover subscribing to addresses, receiving webhooks, handling retries, and integrating with other FluxRail products like Payouts and Liquidity. All examples use plain HTTP requests—no SDKs, just curl and fetch.

Step 1: Set Up Your Webhook Endpoint

Before subscribing to events, you need an endpoint to receive them. FluxRail sends POST requests with a JSON payload and an HMAC SHA-256 signature in the X-FluxRail-Signature header. Always verify this signature to ensure the request is from FluxRail.

Here's a simple Node.js Express endpoint that verifies the signature and processes the event:

const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

const FLUXRAIL_WEBHOOK_SECRET = 'your_webhook_secret';

app.post('/webhooks/fluxrail', (req, res) => {
  const signature = req.headers['x-fluxrail-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', FLUXRAIL_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Handle different event types
  switch (event.type) {
    case 'address.activity':
      // Process incoming/outgoing transactions
      break;
    case 'contract.event':
      // Process smart contract events
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

In production, use a secure secret and store it in environment variables. FluxRail signs all webhooks with the secret you provide when creating the webhook endpoint.

Step 2: Register Your Webhook with FluxRail

Next, tell FluxRail where to send events. Use the POST /api/v1/webhooks endpoint to register your URL. You can specify which event types you want to receive.

curl -X POST https://api.fluxrail.io/api/v1/webhooks \
  -H "X-API-Key: flux_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/fluxrail",
    "events": ["address.activity", "contract.event"],
    "secret": "your_webhook_secret"
  }'

The response includes the webhook ID. Save it for managing the webhook later.

Step 3: Subscribe to Blockchain Addresses or Contracts

Now create subscriptions to the addresses or contracts you want to monitor. FluxRail supports bulk creation for efficiency.

To watch a single Ethereum address:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "webhook_id": "wh_12345"
  }'

For multiple addresses, use the bulk endpoint:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions/bulk \
  -H "X-API-Key: flux_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": [
      { "chain": "ethereum", "address": "0x...", "webhook_id": "wh_12345" },
      { "chain": "polygon", "address": "0x...", "webhook_id": "wh_12345" }
    ]
  }'

You can also subscribe to smart contract events by specifying the contract address and event signature.

Step 4: Handle Events and Trigger Business Logic

When a transaction occurs, FluxRail sends a webhook with details. Here's an example payload for an address.activity event:

{
  "id": "evt_123",
  "type": "address.activity",
  "created_at": "2025-01-15T10:00:00Z",
  "data": {
    "chain": "ethereum",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "transaction_hash": "0xabc...",
    "from": "0x...",
    "to": "0x...",
    "value": "1.5",
    "token": "ETH",
    "status": "confirmed"
  }
}

In your webhook handler, you can now credit user balances, send notifications, or trigger a payout. For example, if you're a remittance app, you might automatically initiate a fiat payout when a stablecoin deposit is confirmed.

Step 5: Ensure Reliability with Retries and Logs

FluxRail automatically retries failed webhook deliveries with exponential backoff. You can view delivery attempts and manually retry events if needed.

To check webhook logs:

curl https://api.fluxrail.io/api/v1/webhooks/wh_12345/deliveries \
  -H "X-API-Key: flux_live_xxx"

To retry a specific event:

curl -X POST https://api.fluxrail.io/api/v1/events/evt_123/retry \
  -H "X-API-Key: flux_live_xxx"

Always make your webhook handler idempotent to handle duplicate deliveries gracefully.

Step 6: Integrate with Payouts and Liquidity

Once you detect a deposit, you might want to convert it to fiat and send it to a bank account. FluxRail's Liquidity and Payouts products make this seamless.

First, get a firm quote to convert USDC to USD:

curl -X POST https://api.fluxrail.io/api/v1/liquidity/quote \
  -H "X-API-Key: flux_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_token": "USDC",
    "to_token": "USD",
    "amount": "1000"
  }'

Then execute the swap and initiate a payout to a bank account:

curl -X POST https://api.fluxrail.io/api/v1/liquidity/execute/q_123 \
  -H "X-API-Key: flux_live_xxx"

For payouts, create a customer and send funds:

curl -X POST https://api.fluxrail.io/api/v1/payouts/customers/user-101/send \
  -H "X-API-Key: flux_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "network": "ERC20",
    "amount": "250",
    "dest_currency": "USD",
    "method": "ach",
    "destination": {
      "account_owner_name": "Jane Doe",
      "account_number": "000123456789",
      "routing_number": "110000000",
      "account_type": "checking"
    }
  }'

FluxRail handles compliance, sanctions screening, and settlement across 75+ countries.

Step 7: Monitor and Scale

Use FluxRail's stats endpoints to monitor subscription counts and event volumes. The GET /api/v1/events/stats endpoint provides insights into event throughput, helping you scale your infrastructure.

For high-volume applications, consider using multiple webhook endpoints and load balancing. FluxRail's reliable delivery ensures no event is lost.

Conclusion

Building real-time event-driven applications with FluxRail is straightforward: register a webhook, subscribe to addresses, and handle events. With built-in retries, signature verification, and seamless integration with Payouts and Liquidity, FluxRail provides the infrastructure you need to focus on your product. Start building today with your API key from fluxrail.io.