Sparrow

Self-hosted webhook delivery. Retries, signing, health tracking, and a dashboard, with PostgreSQL as the only dependency.

Quick start · What you get · Satellites · Documentation · Contributing

Sparrow is open-source webhooks as a service that you host yourself, a self-hosted alternative to Svix, Hookdeck and Convoy. It sends your webhooks so you don't have to build the boring, hard parts: async fan-out, retries with backoff, Standard Webhooks signatures, per-endpoint health, full delivery history, and a consumer portal where your customers manage their own endpoints.

It is one Go binary with an embedded Svelte dashboard. No Redis, no broker, no sidecar workers. PostgreSQL holds the data and, through River, the job queue too. Payloads never leave your network.

your services ──▶ Sparrow API + dashboard ──▶ PostgreSQL + River ──▶ signed deliveries to subscribers

Quick start

Run it with Docker Compose. No clone, no secrets, ready for local evaluation:

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

Open http://localhost:8080 for the dashboard and http://localhost:8080/docs for the interactive API reference. Most things (registering event types and webhooks, pushing a test event, inspecting every delivery attempt) can be done in the dashboard, and we recommend starting there to get a feel for Sparrow. If port 8080 is taken, start it with SPARROW_PORT=8090 docker compose up -d and use that port instead. docker compose down -v cleans up.

Send your first webhook with the CLI. Install it in one line (macOS and Linux; it verifies the release checksum, and re-running it updates in place):

curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh

Then, in two terminals:

sparrow init --url http://localhost:8080        # point the CLI at your server
sparrow listen --event order.created            # receive deliveries right here (Ctrl-C cleans up)

sparrow push order.created -d '{"order_id":"ord_1","amount":42}'

The delivery shows up in the first terminal, signature verified. Routing that event to Slack is one more command:

sparrow use slack --param webhook_url=https://hooks.slack.com/services/T00/B00/xxx --event order.created

Watch deliveries in a browser with Testhooks, which is what we use to test Sparrow's deliveries: create an endpoint, register its URL as a webhook, and every request shows up with headers and body, signature checked. It is open source (sarathsp06/testhooks), by the same author, and self-hostable.

Prefer curl or a client generated from the OpenAPI spec? Follow the Quickstart. Deploying for real? Start at Production Deployment: the Compose file above is an open, local-only setup on purpose.

What you get

• Reliable delivery: at-least-once, retries with backoff, per-webhook rate limits, 429-aware snoozing, and deterministic bulk re-push and retry.
• Signed and encrypted: HMAC-SHA256 and optional Ed25519 signatures in Standard Webhooks format; secrets and sensitive headers envelope-encrypted at rest; SSRF protection on every outbound request.
• Operable: healthy / degraded / unhealthy per endpoint, automatic pausing of receivers that keep failing, full request and response history, OpenTelemetry traces, metrics, and logs.
• Shaped for the receiver: per-subscription Go templates reshape payloads; shipped recipes turn an event into a Slack, Discord, PagerDuty, ntfy, ClickHouse, Twilio, SendGrid, or CloudEvents call with no glue service.
• Safe to evolve: versioned event types, soft schema validation that warns instead of dropping, and export/import of definitions between environments.
• Self-service for your customers: an embeddable, token-scoped portal where each consumer registers endpoints and inspects and retries their own deliveries.
• One API, documented: OpenAPI 3.1 generated from the Go handlers, served interactively at /docs, committed at api/openapi.yaml.

Curious how it fits together? Read How it works, or explore the interactive architecture diagram.

Satellites

Companion tools that use Sparrow through its public API and never reach inside it. All optional, all in satellites/.

Satellite	What it does
CLI	Push events, tail deliveries, receive webhooks locally, apply recipes, debug templates, and serve an MCP server for AI agents from the terminal.
Recipes	Destination adapters as YAML: a URL plus a transform, applied with sparrow use <name>.
Sources	Bring events in: a cron emitter and Stripe and GitHub receivers that verify and re-publish.
Sinks	Send deliveries beyond HTTP: SMTP email, S3-compatible archiving, and OTLP log export.

Documentation

Everything deeper lives on the docs site: https://sarathsp06.github.io/sparrow/

• Why Sparrow and the note for decision makers
• Installation and Configuration, every environment variable in one place
• Guides: verifying signatures in nine languages, payload transformation, event type versioning, health alerts, embedding the portal
• Deployment: production, access tokens and invites, securing Sparrow, upgrading to 1.0
• Reference: architecture, API reference, API errors, , ,

The Docker image is at ghcr.io/sarathsp06/sparrow, prebuilt binaries on the releases page.

Contributing

git clone https://github.com/sarathsp06/sparrow.git && cd sparrow
make dev-db          # throwaway Postgres on localhost:5432
make run             # server on :8080, migrations run on startup
make test            # all modules

make help lists every target, CONTRIBUTING.md has the workflow, AGENTS.md the architecture notes and conventions, CHANGELOG.md what changed in each release, and GOVERNANCE.md who decides what. Everyone taking part follows the Code of Conduct.

License

MIT

Star History