[P0] Build Webhook Infrastructure for Event-Driven Notifications

[BlocksScanIO]

Feature Request: Webhook Infrastructure for Event-Driven Notifications

Background

Competitor Analysis Reference: QuickNode Webhooks, Alchemy Notify

QuickNode's Webhook product allows developers to receive real-time blockchain notifications without maintaining WebSocket connections. This is critical for serverless architectures and mobile backends.

Requirements

Core Features

• HTTP webhook delivery for blockchain events
• No-code template system for common use cases
• Guaranteed delivery with exponential backoff retries
• Automatic reorg handling and redelivery
• Webhook signature verification (HMAC-SHA256)

Event Types

1. Address Activity - Incoming/outgoing transactions for watched addresses
2. Contract Events - Specific event signatures from smart contracts
3. Block Confirmations - N-confirmation notifications
4. Gas Price Alerts - Threshold-based notifications
5. Mempool Monitoring - Pending transaction detection

Technical Specifications

• Delivery Timeout: 30 seconds per webhook
• Retry Policy: Exponential backoff (1s, 2s, 4s, 8s, 16s, 32s)
• Max Retries: 6 attempts over ~60 seconds
• Payload Size Limit: 1MB
• Signature Header: X-XDC-Signature: sha256=<hmac>

Implementation Plan

Architecture

package webhooks

type Webhook struct {
    ID          string
    URL         string
    EventType   EventType
    Filters     FilterCriteria
    Secret      string // For HMAC signing
    Status      Status
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

type Delivery struct {
    ID          string
    WebhookID   string
    Payload     []byte
    Status      DeliveryStatus
    Attempts    []Attempt
    CreatedAt   time.Time
}

type Dispatcher struct {
    queue       chan *Delivery
    workers     int
    client      *http.Client
    retryPolicy RetryPolicy
}

Database Schema

CREATE TABLE webhooks (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    url VARCHAR(2048) NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    filters JSONB,
    secret VARCHAR(256),
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE webhook_deliveries (
    id UUID PRIMARY KEY,
    webhook_id UUID REFERENCES webhooks(id),
    payload JSONB NOT NULL,
    signature VARCHAR(128),
    status VARCHAR(20),
    attempts INT DEFAULT 0,
    response_status INT,
    response_body TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    delivered_at TIMESTAMP
);

API Endpoints

POST /api/v1/webhooks
{
  "url": "https://myapp.com/xdc-webhook",
  "event_type": "address_activity",
  "filters": {
    "addresses": ["0x..."],
    "confirmations": 12
  }
}

GET /api/v1/webhooks
GET /api/v1/webhooks/:id
DELETE /api/v1/webhooks/:id
GET /api/v1/webhooks/:id/deliveries
POST /api/v1/webhooks/:id/test

Webhook Payload Format

{
  "event_type": "address_activity",
  "webhook_id": "wh_123456",
  "delivery_id": "del_789012",
  "timestamp": "2026-02-26T20:33:00Z",
  "data": {
    "transaction": {
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "gas_price": "20000000000",
      "block_number": 12345678,
      "confirmations": 12
    }
  }
}

No-Code Templates

Template	Description	Filters
Wallet Monitor	Track address activity	Address list
NFT Tracker	Monitor NFT transfers	Contract address
DeFi Alerts	Track DEX trades	DEX contracts
Gas Monitor	Alert on gas spikes	Threshold
Mempool Watcher	Pending tx alerts	Address/contract

Security Requirements

• HMAC-SHA256 signature verification
• HTTPS-only webhook URLs
• IP allowlist option
• Rate limiting per webhook
• Payload encryption option (AES-256)

Acceptance Criteria

• Webhook creation via API and dashboard
• 99.9% delivery success rate for healthy endpoints
• <5s latency from block to webhook delivery
• Reorg handling with redelivery
• Webhook testing endpoint
• Delivery logs and retry history

Competitor Comparison

Feature	QuickNode	Alchemy	XDC Gateway (Target)
Webhooks	✅	✅	🔄 Planned
No-Code	✅	❌	✅
Reorg Handling	✅	✅	✅
Guaranteed Delivery	✅	✅	✅
Pricing	Per delivery	Per call	TBD

References

• QuickNode Webhooks
• Alchemy Notify
• Stripe Webhook Best Practices

Priority: P0 - Critical for serverless and mobile backends
Estimated Effort: 6 weeks
Labels: enhancement, infrastructure, P0, webhooks