Webhooks Overview

FortiBlox Nexus Webhooks enable event-driven architectures by delivering real-time notifications directly to your application when blockchain events occur. Instead of constantly polling for updates, webhooks push data to your endpoints instantly, reducing latency and infrastructure costs.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when specific blockchain events occur. When an event matches your subscription criteria, FortiBlox sends a POST request to your configured endpoint with the event data.

Key Benefits

• Real-time notifications - Receive updates within seconds of on-chain events
• Reduced complexity - No need to manage WebSocket connections or polling loops
• Lower costs - Pay only for events you receive, not for continuous connections
• Scalable architecture - Built-in retry logic and delivery guarantees
• Event-driven design - Build reactive applications that respond to blockchain activity

How Webhooks Work

sequenceDiagram
    participant Blockchain as X1 Blockchain
    participant Nexus as FortiBlox Nexus
    participant App as Your Application

    App->>Nexus: 1. Register webhook endpoint
    Blockchain->>Nexus: 2. Transaction confirmed
    Nexus->>Nexus: 3. Match filters
    Nexus->>App: 4. POST webhook event
    App->>Nexus: 5. Return 200 OK

1. Register - Configure webhook endpoints and event filters via API or dashboard
2. Monitor - FortiBlox monitors the blockchain for matching events
3. Filter - Events are matched against your subscription criteria
4. Deliver - Matching events are sent to your endpoint via HTTP POST
5. Confirm - Your application responds with 200 OK to acknowledge receipt

Use Cases

Payment Processing

Receive instant notifications when payments are received to your wallets:

// Webhook payload when payment received
{
  "event": "account.updated",
  "account": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "balance": 1000000000, // 1 SOL
  "slot": 150234567,
  "timestamp": "2024-01-15T10:30:00Z"
}

Use cases:

• E-commerce payment confirmations
• Cryptocurrency payment gateways
• Automated accounting systems
• Wallet balance monitoring

DeFi Protocol Monitoring

Track DEX swaps, liquidity events, and protocol interactions:

// Webhook for Jupiter swap
{
  "event": "transaction.confirmed",
  "signature": "5wHu...",
  "accounts": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
  "program": "Jupiter Aggregator",
  "swap": {
    "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputMint": "So11111111111111111111111111111111111111112",
    "amount": 1000000
  }
}

Use cases:

• Trading bot triggers
• Liquidity pool monitoring
• Protocol analytics
• Arbitrage detection

NFT Marketplace Events

Track NFT listings, sales, and transfers:

// Webhook for Magic Eden sale
{
  "event": "transaction.confirmed",
  "signature": "2bK9...",
  "nft": {
    "mint": "DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6WK3GChEySUpHSS4x",
    "collection": "DRiP",
    "sale_price": 50000000,
    "buyer": "Buyer1111...",
    "seller": "Seller2222..."
  }
}

Use cases:

• NFT marketplace notifications
• Collection floor price tracking
• Rarity sniper alerts
• Portfolio tracking

Blockchain Monitoring

Monitor block production and network health:

// Webhook for new block
{
  "event": "block.confirmed",
  "slot": 150234567,
  "blockhash": "9gZe...",
  "parent_slot": 150234566,
  "transaction_count": 3421,
  "timestamp": "2024-01-15T10:30:00Z"
}

Use cases:

• Block explorers
• Network monitoring dashboards
• Validator performance tracking
• Analytics platforms

Event Types

FortiBlox Webhooks support three main event categories:

Transaction Events

Account Events

Block Events

Filtering Options

Create precise subscriptions with powerful filtering:

Account Filters

{
  "account_include": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
  "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
  "owner": "11111111111111111111111111111111" // System program
}

Transaction Filters

{
  "program_id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
  "success": true, // Only successful transactions
  "failed": false, // Exclude failed transactions
  "vote_transactions": false // Exclude vote transactions
}

Advanced Filters

{
  "commitment": "confirmed", // or "finalized"
  "min_amount": 1000000, // Minimum 0.001 SOL
  "token_transfers": true, // Include token transfer data
  "instruction_filters": ["transfer", "swap"]
}

Delivery Guarantees

At-Least-Once Delivery

FortiBlox guarantees at-least-once delivery with automatic retries:

• Immediate retry if endpoint returns 5xx error
• Exponential backoff - 1s, 2s, 4s, 8s, 16s, 32s, 64s
• Maximum 7 retries over ~2 minutes
• Dead letter queue for failed deliveries after all retries

Idempotency

Handle duplicate deliveries gracefully using the event ID:

const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const { event_id, ...eventData } = req.body;

  // Check if already processed
  if (processedEvents.has(event_id)) {
    return res.status(200).json({ status: 'already_processed' });
  }

  // Process event
  processEvent(eventData);
  processedEvents.add(event_id);

  res.status(200).json({ status: 'success' });
});

Security

Webhooks are secured using HMAC-SHA256 signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Learn more about webhook security →

Subscription Tiers

Rate Limits

Endpoint Requirements

Your webhook endpoint must:

• Respond within 5 seconds - Longer responses may timeout
• Return 2xx status code - Any other code triggers retry
• Support HTTPS - HTTP endpoints are not supported (except localhost for testing)
• Accept POST requests - With Content-Type: application/json

Rate Limiting

• Maximum 1000 events/second per endpoint
• Maximum 10MB payload size
• Connection timeout: 5 seconds
• Read timeout: 10 seconds

Next Steps

Support

• Discord: discord.gg/fortiblox
• Email: [email protected]
• Status: status.fortiblox.com