sparrow

Sparrow

Self-hosted webhook delivery platform with async fan-out, retries, health tracking, and observability. Built for teams that need reliable outbound webhooks without depending on a third-party service.

Features

• Event-driven fan-out -- push one event, deliver to all matching subscriptions
• Reliable delivery -- at-least-once semantics with configurable retries and exponential backoff
• Payload transformation -- Go templates per subscription to reshape payloads before delivery
• Health tracking -- per-webhook success rates, error classification, and automatic degradation detection
• HMAC signing -- every delivery is signed so receivers can verify authenticity
• Encryption at rest -- webhook secrets and sensitive headers are envelope-encrypted (AES-256-GCM) with auto-generated keys
• Dual-protocol API -- gRPC on :50051 and Connect-RPC (HTTP/JSON) on :8080
• Web dashboard -- embedded UI for managing webhooks, events, deliveries, and health
• Observability -- OpenTelemetry traces, metrics, and structured logs via OTLP

Quick Start

Download deploy/docker-compose.yml and start it:

curl -O https://raw.githubusercontent.com/sarathsp06/sparrow/main/deploy/docker-compose.yml
docker compose up -d

Open http://localhost:8080 for the web UI.

Send your first event

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

# Register a webhook (subscription is created automatically)
curl -X POST http://localhost:8080/webhook.WebhookService/RegisterWebhook \
  -H "Content-Type: application/json" \
  -d '{"namespace": "default", "url": "https://httpbin.org/post", "events": ["order.created"], "active": true}'

# Push an event -- Sparrow fans out and delivers
curl -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}}'

Check delivery status in the web UI at Deliveries, or query the API:

curl -X POST http://localhost:8080/webhook.DeliveryService/ListDeliveries \
  -H "Content-Type: application/json" \
  -d '{"namespace": "default", "limit": 5}'

Use Cases

• SaaS webhook notifications -- notify customer endpoints when resources change
• Internal event bus -- fan out domain events to downstream services over HTTP
• Reliability layer -- add retries, health tracking, and observability to existing webhook flows
• Development and testing -- inspect deliveries, replay failed events, test payload transforms

Architecture

PushEvent API
  -> persist event in PostgreSQL
  -> enqueue fan-out job (River)
     -> match subscriptions, apply transforms, create deliveries
     -> enqueue delivery jobs
        -> HTTP POST with HMAC signature
        -> retry on failure (server errors, timeouts, network errors)
        -> track health per webhook

Events are persisted before delivery. The River job queue provides at-least-once delivery with configurable retries (default: 3 attempts, 60s backoff). Failures are classified into retryable (5xx, timeout, connection refused, network error) and non-retryable (4xx, DNS, TLS) categories. Webhook secrets and sensitive headers are envelope-encrypted at rest using AES-256-GCM with per-record data encryption keys.

See the architecture reference for the full pipeline design, error classification, and health state machine.

Configuration

All configuration is via environment variables:

See the configuration reference for the full list.

Deployment

Railway

Deploy Sparrow + PostgreSQL on Railway with zero infrastructure. See the Railway deployment guide for setup steps.

Docker

Pre-built multi-arch images (linux/amd64, linux/arm64) are published on every release:

docker pull ghcr.io/sarathsp06/sparrow:latest

See Docker Compose deployment guide for details.

Kubernetes

A Helm chart is included at charts/sparrow/:

helm install sparrow charts/sparrow/ \
  --set secrets.databaseURL="postgres://user:pass@your-db:5432/sparrow?sslmode=require"

See Kubernetes deployment guide for all chart values and examples.

Documentation

sarathsp06.github.io/sparrow

• Getting Started -- installation and quickstart
• API Reference -- all RPCs and message types
• Architecture -- system design overview

API reference docs are generated from webhook.proto using proto2astro.

In-repo docs: Configuration | Architecture | Kubernetes | webhook.proto

Contributing

Contributions are welcome. Please open an issue to discuss larger changes before submitting a PR.

git clone https://github.com/sarathsp06/sparrow.git
cd sparrow
make build-with-ui   # build server + embedded UI
make test            # run tests
make lint            # run linters

See the architecture reference for the package structure and dependency graph.

License

MIT