Skip to content

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
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.

One flow that uses three satellites, none of which needs code:

  1. Source: sparrow-sources receives Stripe’s payment_intent.succeeded webhook, checks the Stripe-Signature, and pushes stripe.payment_intent.succeeded into Sparrow with labels source=stripe and livemode=true. See Sources.
  2. Recipe: a webhook created with sparrow use slack --event stripe.payment_intent.succeeded posts each payment to a Slack channel. Sparrow renders the message itself; nothing else runs. See Recipes.
  3. Sink: a second webhook points at sparrow-sinks, whose S3 sink writes each delivery’s envelope to events/stripe.payment_intent.succeeded/2026/10/08/<event_id>.json for 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.

Anything you build against the same three rules inherits the whole pipeline:

  1. Public API only — no database access, no server internals.
  2. Verify signatures — check the Standard Webhooks headers before trusting a delivery.
  3. Fail loudly, stay stateless — return non-2xx and let Sparrow’s retries do the work.