Architecture
How HookSniff works under the hood — system components, data flow, and technology choices.
System Overview
HookSniff consists of four main components:
┌─────────────────┐
│ Internet │
└────────┬────────┘
│
┌────────▼────────┐
│ TLS Proxy │
│ (Fly.io) │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │ │
┌────────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐
│ API Server │ │ Dashboard │ │ Healthcheck │
│ (Axum/Rust) │ │ (Next.js) │ │ (internal) │
└──┬──┬──┬───────┘ └─────┬─────┘ └───────────────┘
│ │ │ │
│ │ └───────────────┼────► PostgreSQL (Neon)
│ │ │
└──┼──────────────────┼────► Redis
│ │
└──────────────────┼────► PostgreSQL Queue
│
▼
┌───────────┐
│ Worker │
│ (Rust) │
└─────┬─────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ HTTP │ │ gRPC │ │ SQS │
│ Delivery │ │ Delivery │ │ Delivery │
└──────────┘ └──────────┘ └──────────┘Components
API Server
Async REST API built with Axum (Rust). Handles authentication, webhook ingestion, rate limiting, and idempotency.
- • PostgreSQL via SQLx (Neon in production)
- • PostgreSQL-based queue (
webhook_queuetable) - • API keys (
hr_live_*) + JWT auth - • SSRF protection, payload validation
- • Prometheus metrics at
/metrics
Worker
Webhook delivery engine built with Rust + Tokio. Polls the queue and executes deliveries.
- • HTTP, gRPC, SQS, WebSocket delivery backends
- • HMAC-SHA256 payload signing (Standard Webhooks)
- • Fanout: one event → multiple endpoints
- • Exponential backoff retry with jitter
- • Retry scheduler: polls DB every 30s
docs.dashboard
Web UI built with Next.js 14 (App Router), Tailwind CSS, Radix UI, and Tremor.
- • Endpoint management and monitoring
- • Delivery logs with search and filtering
- • Analytics and charts
- • API key management and billing
Database & Queue
PostgreSQL (Neon) serves as both the primary database and message queue.
- • Customers, endpoints, deliveries, attempts
- •
webhook_queuetable for async delivery - • SSL required (
sslmode=require)
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| API | Rust, Axum, SQLx | Async REST API |
| Worker | Rust, Tokio | Webhook delivery engine |
| docs.dashboard | Next.js 14, Tailwind CSS | Web UI |
| Database | PostgreSQL (Neon) | Persistent storage |
| Queue | PostgreSQL | Async message delivery |
| Auth | JWT + Argon2 + HMAC | Multi-layer auth |
| Billing | Stripe | Payments |
| Deploy | Fly.io | Production hosting |
Data Flow
1. Webhook Ingestion
When you send a webhook via POST /v1/webhooks:
- 1. Authenticate (API key → customer lookup)
- 2. Check idempotency key (return cached response if duplicate)
- 3. Validate event type format and JSON payload depth
- 4. Check payload size (≤ 1 MB) and rate limits
- 5. Verify endpoint exists, is active, matches event filter
- 6. Insert into
deliveriestable (status: pending) - 7. Insert into
webhook_queuefor async processing - 8. Return 200 with delivery ID
2. Webhook Delivery
The Worker polls the queue and delivers webhooks:
- 1. Poll
webhook_queuefor pending deliveries - 2. Look up endpoint URL + signing secret
- 3. Build HTTP request with Standard Webhooks headers
- 4. Send with 30s timeout
- 5. On 2xx: mark as delivered, record attempt
- 6. On failure: record attempt, schedule retry or mark as failed