Getting Started

FalconHook delivers real-time webhook notifications for Algorand blockchain events. Define rules that filter transactions, point them at your endpoint, and receive signed POST requests within milliseconds of block finalization.

Quick Start

1. Register — create your account at /register
2. Create an API key — POST /api/auth/keys
3. Register a webhook endpoint — POST /api/endpoints
4. Create a rule — define filters + link to your endpoint
5. Start receiving webhooks!

Base URL

https://falconhook.com/api

All endpoints below are relative to this base. For example, POST /api/rules → https://falconhook.com/api/rules

Authentication

FalconHook supports two authentication methods: JWT tokens (for web sessions) and API keys (for programmatic access).

JWT Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

// Response: { "access_token": "eyJ...", "token_type": "bearer" }

API Key Authentication

Pass your API key in the X-Api-Key header with every request:

curl -X GET https://falconhook.com/api/rules \
  -H "X-Api-Key: key_your-api-key-here"

Rate Limits

API requests are rate-limited per tenant using a sliding window. Every response includes rate-limit headers so you can track usage.

Response Headers

429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1719500060

{
  "error": "Rate limit exceeded. Limit: 30 requests/minute",
  "detail": "Rate limit exceeded. Limit: 30 requests/minute",
  "status": 429,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

All error responses follow a consistent JSON format. Every response includes an X-Request-ID header for tracing.

Error Format

{
  "error": "Human-readable error message",
  "detail": "Detailed description",
  "status": 400,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Common Status Codes

API Keys

Manage API keys for programmatic access. The secret is shown only once at creation time — save it securely.

Rules

Rules define which blockchain transactions trigger webhook deliveries. Combine multiple filters for precise matching.

Rule Fields

Create a Rule

POST /api/rules
Content-Type: application/json
X-Api-Key: key_your-key

{
  "name": "whale-payments",
  "txn_type": "pay",
  "min_amount": 1000000000,
  "endpoint_id": 1,
  "max_retries": 6
}

API Routes

Webhook Endpoints

Register your webhook URLs as managed endpoints. Each endpoint gets a unique signing secret (shown only once at creation). Link rules to endpoints via endpoint_id.

Create an Endpoint

POST /api/endpoints
Content-Type: application/json
X-Api-Key: key_your-key

{
  "name": "Production Server",
  "url": "https://yourapp.com/webhook",
  "verification_level": "standard"
}

// Response includes "secret" — save it! It won't be shown again.

Verification Levels

• standard — Challenge-response HMAC verification (default)
• manual — 6-digit code sent to endpoint, confirmed via API

API Routes

Webhook Delivery

When a transaction matches your rule, FalconHook sends a signed POST to your endpoint. The payload format depends on your delivery mode.

Batch Mode (default)

POST https://yourapp.com/webhook
Content-Type: application/json
X-FalconHook-Timestamp: 1719500000
X-FalconHook-Signature: base64-hmac-sha256-signature

{
  "round": 42000000,
  "network": "mainnet",
  "transactions": [
    {
      "txn_id": "TXID...",
      "payload": {
        "sender": "ALGO...",
        "receiver": "ALGO...",
        "amount": 1000000,
        "type": "pay"
      },
      "matched_rules": [
        { "rule": "whale-payments", "project": "Main" }
      ]
    }
  ],
  "idempotency_key": "blk-123-x1"
}

Individual Mode (Pro+)

{
  "round": 42000000,
  "network": "mainnet",
  "transaction": {
    "txn_id": "TXID...",
    "payload": { ... },
    "matched_rules": [
      { "rule": "whale-payments" }
    ]
  },
  "idempotency_key": "dlv-456"
}

Payload Fields

HTTP Headers

Retry Policy

Failed deliveries retry with exponential backoff, configurable per rule. See Retries & Dead Letters for the full backoff schedule, per-plan limits, and dead-letter queue details.

Signature Verification

Every webhook is signed with HMAC-SHA256. Verify the signature to ensure authenticity and prevent replay attacks.

How Signing Works

1. Read the X-FalconHook-Timestamp header (Unix seconds)
2. Build the message: "{timestamp}.{raw_body}"
3. Compute HMAC-SHA256 using your endpoint's signing secret
4. Base64-encode and compare with X-FalconHook-Signature
5. Reject if timestamp is older than 300 seconds (replay protection)

Python Example

import hmac, hashlib, base64, time

def verify(body: bytes, timestamp: str, signature: str, secret: str):
    # Replay protection: reject old timestamps
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Timestamp too old — possible replay attack")
    
    message = f"{timestamp}.".encode() + body
    expected = base64.b64encode(
        hmac.new(secret.encode(), message, hashlib.sha256).digest()
    ).decode()
    
    if not hmac.compare_digest(expected, signature):
        raise ValueError("Invalid signature")

Node.js Example

const crypto = require('crypto');

function verify(body, timestamp, signature, secret) {
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
  if (age > 300) throw new Error('Timestamp too old');

  const message = timestamp + '.' + body;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('base64');

  if (expected !== signature) throw new Error('Invalid signature');
}

Retries & Dead Letters

Failed webhook deliveries (4xx / 5xx responses) are retried with exponential backoff. After all attempts are exhausted, the delivery moves to the dead-letter queue for manual inspection and replay.

Backoff Schedule

Delay = min(2^attempt, 60) seconds. Example for 6 retries:

Max Retries by Plan

Dead-Letter Queue

• Deliveries that exceed max_retries move to dead status
• Dead letters are never retried automatically
• Inspect via GET /api/deliveries/dead
• Requeue all with POST /api/deliveries/dead/requeue
• Or replay individual deliveries with POST /api/deliveries/{id}/replay

HTTP 429 Handling

When your endpoint returns 429 Too Many Requests, FalconHook respects the Retry-After header (capped at 120 s) before the next attempt.

Events

Events represent blockchain transactions processed by FalconHook. Query, filter, and manage past events via the API.

Query Parameters

• txn_type — filter by transaction type
• project_id — scope to project
• matched — true/false
• created_at_start / created_at_end — ISO 8601 date range
• limit / offset — pagination

Deliveries

Track, retry, and manage webhook deliveries. Each delivery has a lifecycle: queued → delivering → success | failed → dead.

Replay

Re-evaluate historical events against your current rules. Useful for backfilling or testing new rules against past data.

POST /api/replay/rules/{rule_id}
Content-Type: application/json
X-Api-Key: key_your-key

{
  "from_date": "2025-01-01T00:00:00Z",
  "to_date": "2025-01-31T23:59:59Z",
  "txn_type": "pay",
  "network": "mainnet",
  "limit": 5000
}

// Response:
// {
//   "rule_id": 42,
//   "events_scanned": 5000,
//   "matches_found": 12,
//   "matches": [...]
// }

Real-Time Streaming

In addition to webhooks, subscribe to live events via Server-Sent Events (SSE) or WebSockets.

SSE Example

curl -N -H "X-Api-Key: key_your-key" \
  https://falconhook.com/api/events/stream

FAQ