How It Works

hookstream is an event gateway that sits between webhook senders and your applications. It receives webhooks (via Sources), routes them (via Connections), and delivers them (to Destinations) — with retries, circuit breakers, and real-time monitoring built in.

Ingest

When a webhook arrives at a source URL, hookstream runs it through the ingest pipeline:

1. Verify the signature (if configured) using HMAC-SHA256, SHA-1, or the Standard Webhooks spec.
2. Check IP allowlist/denylist against the request's source IP.
3. Deduplicate against a sliding KV-backed window so retried sends from the provider don't double-process.
4. Persist the event in D1 with the full method, headers, body, query params, and metadata.
5. Offload large payloads (over 10 KB) to R2 object storage; small payloads stay inline in D1.

See Sources for configuration details and 15+ provider templates for one-click setup.

Routing

Each connection defines a source-to-destination route with optional:

• Content-based filters — 9 operators (eq, neq, contains, gt, gte, lt, lte, exists, in) with dot-notation field paths.
• JSONata transforms — reshape the payload before delivery without leaving the sandbox.
• JSON Schema validation — reject or warn on malformed events.

An event can match multiple connections, enabling fan-out to many destinations from a single source.

Delivery

Each destination gets its own Durable Object (DeliveryScheduler) that owns:

• Immediate delivery via the configured provider (HTTP, SQS, S3, EventBridge, Pub/Sub, Kafka, RabbitMQ, or WebSocket).
• Retries on failure with exponential, linear, or fixed backoff.
• Circuit breaker — opens after 5 consecutive failures, probes with a half-open request, auto-closes on success.
• Dead letter queue for events that exhaust every retry.

Every attempt is recorded with status code, latency, and error message — visible in the dashboard and via the delivery-attempts API.

Monitoring

hookstream gives you real-time visibility through:

• WebSocket push to the dashboard via a per-org EventStream Durable Object (Hibernatable WebSockets — no idle cost).
• Metrics for event volume, delivery success rate, latency percentiles, and error breakdown.
• Issues auto-created on delivery failure with severity and affected resources.
• Alert rules — 5 types: failure rate, latency, volume drop, DLQ growth, issue opened.
• Notification channels — HMAC-signed webhooks or email via Resend.

Architecture

The happy path for a single event:

text
Provider
  -> Source (ingest URL)
  -> Pipeline (verify + filter + transform + validate)
  -> Connection
  -> DeliveryScheduler DO
  -> Destination Provider
  -> Your Endpoint

All backend logic runs on Cloudflare Workers with Durable Objects for stateful operations. Data lives in D1 (SQLite), KV (cache, dedup, rate limits), and R2 (large payloads). Auth is Better Auth — session cookies for the dashboard, API keys for machine clients.

Next Steps