FortiBlox LogoFortiBlox Docs
NexusWebhooks

Webhook Events Reference

Complete reference of all FortiBlox webhook events, payloads, and filtering options

Webhook Events Reference

This page provides a complete reference of all webhook events available in FortiBlox Nexus, including payload structures, filtering options, and examples.

Event Categories

FortiBlox webhooks support three main event categories:

  1. Transaction Events - Transaction confirmations, failures, and updates
  2. Account Events - Account balance and data changes
  3. Block Events - New blocks and finalization (Professional+ only)

Transaction Events

transaction.confirmed

Fired when a transaction reaches confirmed commitment level.

Availability: Business tier and above

Payload Structure:

{
  "event_id": "evt_1a2b3c4d5e6f",
  "event": "transaction.confirmed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "signature": "5wHu7KQKVqJz3ZLPkZ9tR6HvQXYYJZVcXWVLXXKqKQE...",
    "slot": 150234567,
    "block_time": 1705318245,
    "fee": 5000,
    "success": true,
    "error": null,
    "accounts": [
      "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
    ],
    "program_ids": [
      "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
    ],
    "instructions": [
      {
        "program_id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instruction": "swap",
        "accounts": [...],
        "data": "..."
      }
    ],
    "token_transfers": [
      {
        "from": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
        "to": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "amount": "1000000",
        "decimals": 6
      }
    ],
    "log_messages": [
      "Program JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4 invoke [1]",
      "Program log: Instruction: Swap",
      "Program JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4 success"
    ]
  }
}

Filter Options:

{
  "events": ["transaction.confirmed"],
  "filters": {
    // Account filters
    "account_include": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
    "account_exclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],

    // Program filters
    "program_id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",

    // Transaction status
    "success": true,
    "vote_transactions": false,

    // Amount filters (in lamports)
    "min_amount": 1000000,
    "max_amount": 1000000000,

    // Additional data
    "include_token_transfers": true,
    "include_logs": true
  }
}

Example Use Cases:

  • Monitor DEX swaps on Jupiter or Orca
  • Track NFT sales on Magic Eden
  • Alert on large transactions
  • Detect failed transaction attempts

transaction.finalized

Fired when a transaction reaches finalized commitment level.

Availability: Business tier and above

Payload Structure: Same as transaction.confirmed with event: "transaction.finalized"

Key Differences:

  • Higher latency (~400ms vs ~200ms for confirmed)
  • Permanent - will not be rolled back
  • Recommended for financial applications

Filter Options: Same as transaction.confirmed

transaction.failed

Fired when a transaction fails.

Availability: Business tier and above

Payload Structure:

{
  "event_id": "evt_9z8y7x6w5v4u",
  "event": "transaction.failed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "signature": "3kJH2pKLMnB4QvRzH8sY6NtV9XqZKLMnB4QvRzH8sY6...",
    "slot": 150234567,
    "error": {
      "type": "InstructionError",
      "index": 0,
      "message": "custom program error: 0x1"
    },
    "accounts": [...],
    "program_ids": [...],
    "fee": 5000
  }
}

Filter Options:

{
  "events": ["transaction.failed"],
  "filters": {
    "account_include": ["YourProgramAddress..."],
    "error_types": ["InstructionError", "InsufficientFundsForRent"]
  }
}

Example Use Cases:

  • Debug transaction failures
  • Alert users of failed payments
  • Monitor program errors
  • Track insufficient balance attempts

Account Events

account.updated

Fired when an account's balance or data changes.

Availability: Business tier and above

Payload Structure:

{
  "event_id": "evt_4u5v6w7x8y9z",
  "event": "account.updated",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "account": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "slot": 150234567,
    "lamports": 1000000000,
    "owner": "11111111111111111111111111111111",
    "executable": false,
    "rent_epoch": 361,
    "data": "base64-encoded-data...",
    "data_size": 165,
    "changes": {
      "lamports": {
        "old": 500000000,
        "new": 1000000000,
        "delta": 500000000
      }
    }
  }
}

Filter Options:

{
  "events": ["account.updated"],
  "filters": {
    // Specific accounts to monitor
    "accounts": [
      "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    ],

    // Filter by owner program
    "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",

    // Balance change thresholds (in lamports)
    "min_balance_change": 1000000,

    // Include account data
    "include_data": true,
    "data_encoding": "base64" // or "base58", "jsonParsed"
  }
}

Example Use Cases:

  • Monitor wallet balances
  • Track token account changes
  • Alert on large deposits/withdrawals
  • Update user balance displays

account.created

Fired when a new account is created.

Availability: Professional tier and above

Payload Structure:

{
  "event_id": "evt_3t4u5v6w7x8y",
  "event": "account.created",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "account": "NewAccount1111111111111111111111111111111",
    "slot": 150234567,
    "lamports": 2039280,
    "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "executable": false,
    "rent_epoch": 361,
    "data_size": 165,
    "creator": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "creation_transaction": "5wHu7KQKVqJz3ZLPkZ9tR6HvQXYYJZVcXWVLXXKqKQE..."
  }
}

Filter Options:

{
  "events": ["account.created"],
  "filters": {
    // Filter by owner program
    "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",

    // Filter by creator
    "creator": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",

    // Minimum initial balance
    "min_balance": 1000000
  }
}

Example Use Cases:

  • Track new token account creations
  • Monitor program deployments
  • Detect new user accounts
  • NFT mint tracking

account.closed

Fired when an account is closed.

Availability: Professional tier and above

Payload Structure:

{
  "event_id": "evt_2s3t4u5v6w7x",
  "event": "account.closed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "account": "ClosedAccount11111111111111111111111111111",
    "slot": 150234567,
    "final_lamports": 0,
    "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "reclaimed_by": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "closing_transaction": "3kJH2pKLMnB4QvRzH8sY6NtV9XqZKLMnB4QvRzH8sY6..."
  }
}

Filter Options:

{
  "events": ["account.closed"],
  "filters": {
    // Filter by owner program
    "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",

    // Filter by rent recipient
    "reclaimed_by": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  }
}

Example Use Cases:

  • Track token account closures
  • Monitor rent reclamation
  • Detect wallet cleanup activities
  • Audit account lifecycle

Block Events

block.confirmed

Fired when a new block is confirmed.

Availability: Professional tier and above

Payload Structure:

{
  "event_id": "evt_1r2s3t4u5v6w",
  "event": "block.confirmed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "mainnet",
  "data": {
    "slot": 150234567,
    "parent_slot": 150234566,
    "blockhash": "9gZe3d7pNq5XvQPRzWj8kL4mH6nC2vB1xY5sA8tD7fK",
    "previous_blockhash": "8fY9dZ2c6pMn4WuQPyVi7jK3lG5mB1vC0xW4rA7sC6eJ",
    "block_time": 1705318245,
    "block_height": 145123456,
    "transaction_count": 3421,
    "successful_transactions": 3398,
    "failed_transactions": 23,
    "vote_transactions": 2156,
    "rewards": [
      {
        "pubkey": "ValidatorAddress...",
        "lamports": 10000,
        "post_balance": 500000000000,
        "reward_type": "Voting"
      }
    ]
  }
}

Filter Options:

{
  "events": ["block.confirmed"],
  "filters": {
    // Minimum transaction count
    "min_transaction_count": 1000,

    // Include transaction details
    "include_transactions": false,

    // Include rewards
    "include_rewards": true
  }
}

Example Use Cases:

  • Block explorer real-time updates
  • Network monitoring dashboards
  • Validator performance tracking
  • Block production analytics

block.finalized

Fired when a block is finalized.

Availability: Professional tier and above

Payload Structure: Same as block.confirmed with event: "block.finalized"

Key Differences:

  • Higher latency (~30-60 seconds)
  • Permanent - will not be rolled back
  • Recommended for critical applications

Combined Event Subscriptions

You can subscribe to multiple events in a single webhook:

{
  "url": "https://api.yourdomain.com/webhook",
  "events": [
    "transaction.confirmed",
    "transaction.finalized",
    "account.updated"
  ],
  "filters": {
    "account_include": ["YourAddress..."],
    "success": true
  }
}

Advanced Filtering

Token Transfer Filters

Monitor specific token transfers:

{
  "events": ["transaction.confirmed"],
  "filters": {
    "token_transfers": {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
      "min_amount": 1000000, // 1 USDC
      "from": "YourAddress...", // Optional
      "to": "YourAddress..." // Optional
    }
  }
}

NFT-Specific Filters

Track NFT mints and sales:

{
  "events": ["transaction.confirmed"],
  "filters": {
    "nft": {
      "marketplaces": ["M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"], // Magic Eden
      "collection": "YourCollectionAddress...",
      "event_types": ["sale", "listing", "bid"]
    }
  }
}

DeFi Protocol Filters

Monitor specific DeFi protocols:

{
  "events": ["transaction.confirmed"],
  "filters": {
    "defi": {
      "protocols": ["jupiter", "orca", "raydium"],
      "event_types": ["swap", "add_liquidity", "remove_liquidity"],
      "min_usd_value": 1000
    }
  }
}

Webhook Payload Headers

Every webhook delivery includes these headers:

Content-Type: application/json
X-Fortiblox-Signature: sha256=abc123...
X-Fortiblox-Event: transaction.confirmed
X-Fortiblox-Event-ID: evt_1a2b3c4d5e6f
X-Fortiblox-Timestamp: 1705318245
X-Fortiblox-Delivery-ID: del_9z8y7x6w5v4u
X-Fortiblox-Attempt: 1

Rate Limits by Event Type

Event TypeMax RateBurst
transaction.confirmed1000/sec2000
transaction.finalized500/sec1000
account.updated500/sec1000
account.created100/sec200
account.closed100/sec200
block.confirmed10/sec20
block.finalized10/sec20

Event Ordering

Events are delivered in the order they occur on-chain, but delivery timing may vary:

  • Confirmed events: ~200-500ms latency
  • Finalized events: ~30-60 seconds latency
  • Retries: May cause out-of-order delivery

Best Practice: Use slot and block_time for ordering, not delivery time.

Testing Events

Send Test Event

curl -X POST https://nexus.fortiblox.com/api/v1/webhooks/wh_abc123/test \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "transaction.confirmed",
    "test_data": {
      "signature": "TestSignature123...",
      "slot": 999999,
      "success": true
    }
  }'

Mock Event Payloads

For local testing, use these mock payloads:

{
  "event_id": "evt_test_123",
  "event": "transaction.confirmed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "devnet",
  "data": {
    "signature": "TestTxSignature...",
    "slot": 100000,
    "success": true,
    "fee": 5000,
    "accounts": ["TestAccount..."],
    "program_ids": ["TestProgram..."]
  }
}
{
  "event_id": "evt_test_456",
  "event": "account.updated",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "devnet",
  "data": {
    "account": "TestAccount...",
    "slot": 100000,
    "lamports": 1000000000,
    "owner": "11111111111111111111111111111111"
  }
}
{
  "event_id": "evt_test_789",
  "event": "block.confirmed",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "network": "devnet",
  "data": {
    "slot": 100000,
    "blockhash": "TestBlockhash...",
    "transaction_count": 100,
    "block_time": 1705318245
  }
}

Next Steps

Security Best Practices

Learn how to secure your webhook endpoints

Code Examples

Production-ready webhook implementations

Getting Started

Set up your first webhook in 5 minutes

API Reference

Complete webhook management API

Support

Questions about webhook events?

Getting Started with Webhooks

Set up your first FortiBlox webhook in 5 minutes - registration, testing, and deployment

Webhook Security

Best practices for securing FortiBlox webhook endpoints with signature verification and security hardening

On this page

Webhook Events ReferenceEvent CategoriesTransaction Eventstransaction.confirmedtransaction.finalizedtransaction.failedAccount Eventsaccount.updatedaccount.createdaccount.closedBlock Eventsblock.confirmedblock.finalizedCombined Event SubscriptionsAdvanced FilteringToken Transfer FiltersNFT-Specific FiltersDeFi Protocol FiltersWebhook Payload HeadersRate Limits by Event TypeEvent OrderingTesting EventsSend Test EventMock Event PayloadsNext StepsSupport