sparrow

Reliable webhook delivery with retries, health tracking, and full observability

Quick Start

Save this docker-compose.yml anywhere and run docker compose up -d -- no need to clone the repo:

# docker-compose.yml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: sparrow
      POSTGRES_USER: sparrow
      POSTGRES_PASSWORD: sparrow
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sparrow"]
      interval: 5s
      timeout: 5s
      retries: 5

  sparrow:
    image: ghcr.io/sarathsp06/sparrow:latest
    environment:
      DATABASE_URL: postgres://sparrow:sparrow@postgres:5432/sparrow?sslmode=disable
      SPARROW_SERVE_UI: "true"
    ports: ["8080:8080", "50051:50051"]
    depends_on:
      postgres: { condition: service_healthy }

docker compose up -d

Open http://localhost:8080/ for the web UI, or use the API directly:

Try It Out

# 1. Register an event type
curl -s -X POST http://localhost:8080/webhook.EventService/RegisterEvent \
  -H "Content-Type: application/json" \
  -d '{"name": "order.created", "description": "New order placed", "active": true}'

# 2. Register a webhook (subscriptions are created automatically)
curl -s -X POST http://localhost:8080/webhook.WebhookService/RegisterWebhook \
  -H "Content-Type: application/json" \
  -d '{"namespace": "default", "url": "https://testhooks.sarathsadasivan.com/hooks", "events": ["order.created"], "active": true}'

# 3. Push an event
curl -s -X POST http://localhost:8080/webhook.EventService/PushEvent \
  -H "Content-Type: application/json" \
  -d '{"namespace": "default", "event": "order.created", "payload": {"order_id": "ord_123", "amount": 99.99}}'

Need a test endpoint? Use https://testhooks.sarathsadasivan.com/hooks -- it accepts any webhook payload and lets you inspect the requests.

Sparrow matches subscriptions, delivers the webhook with retries, and tracks health automatically.

Or Use the Web UI

All of the above -- registering events, creating webhooks with subscriptions, pushing events, inspecting deliveries, and monitoring health -- can be done through the web dashboard at localhost:8080.

1. Events → Register event types, push test events with live schema validation
2. Webhooks → Register webhooks, manage subscriptions with payload transformation templates, pause/resume, edit configuration
3. Deliveries → Inspect delivery status, view request/response bodies, retry failed deliveries
4. Health → Monitor webhook health, view error category breakdowns, track success rates

How It Works

PushEvent
  -> Validate payload against event schema (if defined)
  -> Persist event record
  -> Enqueue fan-out job
     -> Match subscriptions by (namespace, event_name, label_filters)
     -> Apply Go template transformation per subscription (if enabled)
     -> Create one delivery record per matching subscription
     -> Enqueue delivery jobs
        -> HTTP POST to webhook URL with HMAC signature
        -> Record attempt (response code, response time, error category)
        -> On success: mark delivered, update health metrics
        -> On failure: classify error, retry with exponential backoff (if retryable)
        -> Store response body (up to 1 KB by default, 1 MB if capture_response_body is on)

Delivery guarantees: Events are persisted in PostgreSQL before any delivery is attempted. The River job queue provides at-least-once delivery semantics with configurable retries (default: 3 attempts, 60s backoff).

Error classification: Failures are categorized as client_error (4xx, not retried), server_error (5xx, retried), timeout (retried), connection_refused (retried), network_error (retried), dns_error (not retried), or tls_error (not retried).

Health tracking: Per-webhook health is computed from delivery outcomes -- healthy (>90% success rate, <3 consecutive failures), degraded (50-90% or 3-9 consecutive), unhealthy (<50% or 10+ consecutive).

All endpoints are available via both gRPC (:50051) and Connect-RPC HTTP/JSON (:8080).

Configuration

Sparrow is configured entirely via environment variables. No config files needed.

See CONFIGURATION.md for deployment guides and all options.

Kubernetes

A Helm chart is included at charts/sparrow/. Bring your own PostgreSQL or enable the bundled one for evaluation:

# External database (recommended for production)
helm install sparrow charts/sparrow/ \
  --set secrets.databaseURL="postgres://user:pass@your-db:5432/sparrow?sslmode=require"

# Bundled PostgreSQL (evaluation only)
helm install sparrow charts/sparrow/ --set postgresql.enabled=true

See KUBERNETES.md for the full deployment guide, all chart values, and examples.

Documentation

sarathsp06.github.io/sparrow -- Full documentation site with guides, API reference, and deployment instructions.

Quick links:

• Getting Started
• API Reference
• Architecture
• Docker Compose
• Kubernetes

In-repo references:

• CONFIGURATION.md -- All environment variables
• KUBERNETES.md -- Helm chart deployment guide
• TECHNICAL.md -- Architecture deep dive, queue design, health state machine
• ARCHITECTURE.md -- Package structure, dependency graph
• webhook.proto -- Service and message definitions

License

MIT