Building Real-Time Event-Driven Applications with FluxRail: A Step-by-Step Guide

Introduction

Modern applications need to react instantly to blockchain events — token transfers, smart contract calls, or liquidity movements. FluxRail Core provides a unified API to monitor 36+ blockchains in real time, delivering signed webhooks straight to your server. In this guide, you'll build a complete event-driven pipeline: create subscriptions, handle webhooks, verify signatures, and retry failures. No SDKs, no complex infrastructure — just curl and your favorite HTTP client.

Prerequisites

• A FluxRail account (sign up at fluxrail.io)
• An API key (test mode: flux_test_...)
• A publicly accessible HTTPS endpoint to receive webhooks (use webhook.site or ngrok for testing)

1. Get Your API Key and Test Mode

Log in to your FluxRail dashboard, navigate to API Keys, and copy your test key. All requests in this guide use the test key flux_test_abc123. Replace it with your own.

curl https://api.fluxrail.io/api/v1/chains \
  -H "X-API-Key: flux_test_abc123"

This returns a list of supported chains. You'll see slugs like ethereum, polygon, solana, etc.

2. Create a Webhook Endpoint

Before subscribing to events, you need a webhook URL where FluxRail will send events. Register a webhook endpoint:

curl -X POST https://api.fluxrail.io/api/v1/webhooks \
  -H "X-API-Key: flux_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "description": "My event handler",
    "enabled_events": ["*"]
  }'

Response includes an id (e.g., wh_12345) and a secret used for signature verification. Save the secret — you'll need it later.

3. Create a Subscription

Now tell FluxRail what to monitor. Let's watch an Ethereum address for incoming USDC transfers:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "webhook_url": "https://your-server.com/webhook",
    "event_types": ["token_transfer"]
  }'

You can subscribe to multiple addresses at once using the bulk endpoint:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions/bulk \
  -H "X-API-Key: flux_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": [
      {"chain": "polygon", "address": "0x...", "event_types": ["native_transfer"]},
      {"chain": "solana", "address": "Abc...", "event_types": ["native_transfer"]}
    ]
  }'

4. Receive and Verify Webhooks

When a monitored event occurs, FluxRail sends a POST request to your webhook URL with a JSON body and an X-FluxRail-Signature header. The signature is an HMAC-SHA256 of the raw request body using your webhook secret. Verify it before processing:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Example Express middleware
app.post('/webhook', (req, res) => {
  const rawBody = JSON.stringify(req.body);
  const signature = req.headers['x-fluxrail-signature'];
  const secret = 'whsec_...';

  if (!verifySignature(rawBody, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type, event.data);
  res.status(200).send('OK');
});

Always respond with 2xx quickly. FluxRail retries with exponential backoff up to 3 times if you don't respond in time.

5. Handle Event Types

Each event has a type field. Common types: token_transfer, native_transfer, contract_event, transaction_confirmed. Example handler:

switch (event.type) {
  case 'token_transfer':
    // event.data: { from, to, value, token, chain, txHash }
    await creditUser(event.data.to, event.data.value);
    break;
  case 'native_transfer':
    // event.data: { from, to, value, chain, txHash }
    await updateBalance(event.data.to, event.data.value);
    break;
  default:
    console.log('Unhandled event type:', event.type);
}

6. Retry Failed Events

If your webhook fails (non-2xx response), the event's delivery status becomes failed. You can manually retry via the API:

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

Or query all failed events:

curl https://api.fluxrail.io/api/v1/events?status=failed \
  -H "X-API-Key: flux_test_abc123"

7. Monitor Webhook Deliveries

View the delivery log for a specific webhook:

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

Each delivery includes status, response code, and timestamp — useful for debugging.

8. Test Your Integration

FluxRail test mode simulates real events without spending gas. Trigger a test event for your webhook:

curl -X POST https://api.fluxrail.io/api/v1/webhooks/wh_12345/test \
  -H "X-API-Key: flux_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token_transfer",
    "data": {
      "from": "0x123",
      "to": "0x456",
      "value": "1000000",
      "token": "USDC",
      "chain": "ethereum",
      "txHash": "0xabc"
    }
  }'

This sends a fake event to your webhook, allowing you to test your handler end-to-end.

9. Advanced: Filter Events with Event Types

You don't have to subscribe to all events. Specify exact event types when creating a subscription:

curl -X POST https://api.fluxrail.io/api/v1/subscriptions \
  -H "X-API-Key: flux_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "address": "0x...",
    "webhook_url": "https://your-server.com/webhook",
    "event_types": ["native_transfer", "token_transfer"]
  }'

Use the chains endpoint to discover all available event types per chain.

10. Go Live

Once your test integration works, switch to a live API key (flux_live_...). Monitor your webhook deliveries and set up alerts for failures. FluxRail's dashboard provides real-time stats on subscriptions and events.

Conclusion

In this guide, you built a complete event-driven system using FluxRail Core. You created subscriptions, received signed webhooks, verified their authenticity, and handled retries. This architecture scales from a single address to thousands of subscriptions across 36+ chains — all through one unified API. Next steps: combine Core with FluxRail Pay for gas-free transactions, or use Liquidity to automate swaps in response to events. The same webhook pipeline can trigger payouts via FluxRail Payouts, creating a fully automated cross-border payment flow. Check out the full documentation for more patterns.