Satellites
Satellites are companion tools that orbit the core — they use Sparrow, they never reach inside it. Every satellite talks to the same public REST API and signed-webhook contract you do, so the delivery pipeline (matching, retries, signing, audit trail) stays one small, boring server. Delete every satellite and Sparrow still works; add your own and it is a first-class citizen.
Satellites are helper tools, not part of Sparrow itself. The compatibility policy and the threat model cover the core only: a satellite’s commands, flags, config and Go packages can change in any release, so pin the version you use.
graph LR
accTitle: Satellite topology
accDescr: Satellite topology: the outside world (cron schedules, Stripe and GitHub webhooks) flows through inbound Sources, which verify signatures and publish typed events into the Sparrow core (match, retry, sign, audit). The core sends signed deliveries out to Recipes (Slack, Discord, ntfy, PagerDuty, ClickHouse), Sinks (email, S3, OTLP), and your own HTTP endpoints. The CLI talks to the core over REST and local webhooks for push, tail, and listen.
World[World<br>cron · Stripe · GitHub]
World -->|verify signature| Sources[Sources]
Sources -->|publish typed events<br>POST /v1/.../events| Core
subgraph Core[Sparrow core]
Sparrow[match · retry · sign · audit]
end
Sparrow -->|signed delivery| Recipes[Recipes]
Sparrow -->|signed delivery| Sinks[Sinks]
Sparrow -->|signed delivery| Yours[Your HTTP endpoint]
Recipes --> Chat[Slack · Discord · ntfy · PagerDuty · ClickHouse]
Sinks --> Out[Email · S3 · OTLP]
CLI[CLI<br>push · tail · listen] <-->|REST + local webhooks| Sparrow
The satellites
Section titled “The satellites”| Satellite | What it does | Direction |
|---|---|---|
| CLI | Push events, tail deliveries, receive webhooks locally, apply recipes, debug templates — the terminal loop | both |
| Recipes | Adapters as config: one YAML file turns deliveries into Slack, Discord, ntfy, PagerDuty, ClickHouse, Twilio, SendGrid, or CloudEvents payloads — rendered server-side, nothing extra runs | out |
| Sources | Cron schedules plus webhook receivers that verify the provider’s signature and re-publish as typed Sparrow events — see the Sources page for the current provider list | in |
| Sinks | A signed-delivery receiver that forwards to destinations that don’t take webhooks: SMTP email, S3/MinIO archives, and OpenTelemetry log records | out |
Each page explains the satellite’s technical path — exactly which API calls it makes, how signatures are verified, and what happens per delivery.
Example: Stripe payments, end to end
Section titled “Example: Stripe payments, end to end”One flow that uses three satellites, none of which needs code:
- Source:
sparrow-sourcesreceives Stripe’spayment_intent.succeededwebhook, checks theStripe-Signature, and pushesstripe.payment_intent.succeededinto Sparrow with labelssource=stripeandlivemode=true. See Sources. - Recipe: a webhook created with
sparrow use slack --event stripe.payment_intent.succeededposts each payment to a Slack channel. Sparrow renders the message itself; nothing else runs. See Recipes. - Sink: a second webhook points at
sparrow-sinks, whose S3 sink writes each delivery’s envelope toevents/stripe.payment_intent.succeeded/2026/10/08/<event_id>.jsonfor later audit queries. See Sinks.
Sparrow signs, retries and records each of the two deliveries on its own, so a
Slack outage doesn’t hold up the archive. Stripe may deliver the same event
twice; deduplicate downstream on the payload’s id.
The contract
Section titled “The contract”Anything you build against the same three rules inherits the whole pipeline:
- Public API only — no database access, no server internals.
- Verify signatures — check the Standard Webhooks headers before trusting a delivery.
- Fail loudly, stay stateless — return non-2xx and let Sparrow’s retries do the work.