Skip to content

Sinks

sparrow-sinks is a small server you run next to Sparrow. Sparrow delivers to it like to any webhook endpoint, and it passes each delivery on to a destination that doesn’t accept webhooks: an SMTP server, an S3 bucket, or an OpenTelemetry collector. Sparrow’s retries, backoff and delivery history still apply, because to Sparrow the sink is just a webhook URL.

Sink Path on sparrow-sinks Each delivery becomes You need
email POST /sinks/email A plain-text email An SMTP server and its login
s3 POST /sinks/s3 One JSON object in a bucket A bucket and AWS credentials (or MinIO / R2)
otlp POST /sinks/otlp One OpenTelemetry log record An OTLP/HTTP endpoint, such as an OpenTelemetry Collector

GET /healthz returns 200 while the process is up.

If the destination accepts an HTTP request whose auth fits in fixed headers (Slack, PagerDuty, SendGrid), use a recipe instead: Sparrow delivers straight to it and there’s nothing extra to run. Use a sink when the destination speaks another protocol (SMTP, S3’s signed API) or needs a per-request signature such as AWS SigV4.

Install the release binary (macOS and Linux) with the install script:

Terminal window
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh -s -- -c sinks
sparrow-sinks --config sinks.yaml

Or download the sparrow-sinks-* archive for your platform from the releases page, or build it from a checkout with go build ./satellites/sparrow-sinks.

To run it in a container, build a small image from the release binary:

Dockerfile
FROM alpine:3.22
RUN apk add --no-cache curl \
&& curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh \
| sh -s -- -c sinks -b /usr/local/bin
ENTRYPOINT ["sparrow-sinks", "--config", "/etc/sparrow/sinks.yaml"]
Terminal window
docker build -t sparrow-sinks .
docker run -v "$(pwd)/sinks.yaml:/etc/sparrow/sinks.yaml:ro" -p 8788:8788 sparrow-sinks

Each sink is a Go package you can mount on your own server instead of running sparrow-sinks:

Terminal window
go get github.com/sarathsp06/sparrow/satellites/sparrow-sinks
Package What it gives you Dependencies
sinks Handle, Verifier, Envelope: the core every sink is built on standard library
sinks/email email.Config (the email: section) and email.Handler standard library
sinks/otlp otlp.Config (the otlp: section) and otlp.Handler standard library
sinks/s3 s3.Config (the s3: section) and s3.Handler aws-sdk-go-v2

Import only the sinks you use; only sinks/s3 brings in the AWS SDK. Each Config is its YAML section with the sink’s own WebhookSecret or SigningPublicKey (one is required; there is no top-level fallback outside the binary). Your server owns the paths:

import (
"github.com/sarathsp06/sparrow/satellites/sparrow-sinks/sinks/s3"
)
h, err := s3.Handler(ctx, s3.Config{
WebhookSecret: os.Getenv("SPARROW_WEBHOOK_SECRET"),
Bucket: "sparrow-events",
Prefix: "events/",
}, logger)
mux.Handle("POST /archive", h)

To write your own sink, pass a Verifier and a DeliverFunc to sinks.Handle. It verifies the signature, parses the envelope and maps your error to a 502 exactly as the built-in sinks do. The verifier is sinks.HMAC(secret), or sinks.Ed25519(publicKeyHex) to verify with only the webhook’s public key:

import "github.com/sarathsp06/sparrow/satellites/sparrow-sinks/sinks"
verify, err := sinks.Ed25519(webhook.SigningPublicKey) // or sinks.HMAC(secret)
mux.Handle("POST /sinks/kafka", sinks.Handle("kafka", verify, logger,
func(ctx context.Context, env sinks.Envelope, raw []byte) error {
return producer.Send(ctx, env.EventName, raw) // error → 502 → Sparrow retries
}))
  1. Register the event types you want to forward. Sparrow rejects a push to an unregistered type with 404, so nothing would reach the sink:

    Terminal window
    curl -X POST http://localhost:8080/v1/event-types \
    -H 'Content-Type: application/json' \
    -d '{"name": "order.paid"}'
  2. Let Sparrow reach the sink. Sparrow refuses delivery URLs on localhost and private networks by default. If sparrow-sinks runs on a private network, list that network in SPARROW_ALLOWED_NETWORKS on the Sparrow server (for example 10.20.0.0/16). If it runs on the same machine (localhost), start the server with SPARROW_ALLOW_PRIVATE_NETWORKS=true, which is meant for development.

  3. Register one webhook per sink, pointing at the sink’s path, with the events it should receive:

    Terminal window
    curl -X POST http://localhost:8080/v1/consumers/default/webhooks \
    -H 'Content-Type: application/json' \
    -d '{"url": "http://sinks-host:8788/sinks/email", "events": ["order.paid"]}'

    Copy http_config.webhook_secret (whsec_...) from the response. It’s shown only once, and the sink needs it to check signatures.

    To keep the secret out of the sink altogether, register the webhook with "signature_type": "ed25519" and copy signing_public_key instead (it isn’t secret and stays readable on every GET). The sink then verifies the Ed25519 signature with that public key.

  4. Leave transforms off on that webhook’s subscriptions (the default). A sink reads Sparrow’s standard event envelope; a transformed body is rejected with 422. Don’t apply a recipe to a sink webhook.

sparrow-sinks reads one YAML file, sinks.yaml by default (--config to change it; --version prints the version). There are no environment-variable overrides, so keep the file readable only by the user that runs the sink: it holds the webhook secret (unless you use signing_public_key) and the SMTP password. Configure one or more sinks; a sink without a section is not served.

Field Required Default Meaning
listen no :8788 Address to listen on.
webhook_secret this or signing_public_key, unless every sink sets its own The whsec_... secret of the webhook pointing at this server. Verifies the HMAC (v1,) signature every delivery carries.
signing_public_key this or webhook_secret The hex signing_public_key of an ed25519 webhook. Verifies the Ed25519 (v1a,) signature instead, so the sink never holds the secret. Used in place of webhook_secret when both are set.
<sink>.webhook_secret, <sink>.signing_public_key no the top-level values Credentials for one sink. You need these when you register a separate webhook per sink, since each webhook has its own secret and key. A sink that sets either one ignores both top-level values.
sinks.yaml
listen: :8788
email:
webhook_secret: whsec_... # from the webhook pointing at /sinks/email
smtp: {host: smtp.example.com, port: 587, username: sparrow, password: s3cret, starttls: true}
from: sparrow@example.com
to: [ops@example.com]
s3:
webhook_secret: whsec_... # from the webhook pointing at /sinks/s3
bucket: sparrow-events
region: us-east-1

How a delivery is handled, and what Sparrow does with the answer

Section titled “How a delivery is handled, and what Sparrow does with the answer”

For every request, the sink checks the Standard Webhooks signature against the raw body, parses the envelope, then forwards it. It keeps no queue: if forwarding fails it answers 502 and Sparrow retries.

Sink answers When Sparrow then
200 Forwarded to the destination. Marks the delivery succeeded.
400 The body is over 10 MB. Fails it for good (no retry).
401 Signature missing or wrong (wrong webhook_secret or signing_public_key, a public key set for a webhook that isn’t ed25519, or the two machines’ clocks more than 5 minutes apart). Fails it for good. Fix the credential, then retry the failed deliveries.
422 The body isn’t a Sparrow envelope (event_id or event_name missing), almost always because a transform is enabled. Fails it for good. Turn the transform off, then retry.
502 The destination failed: SMTP refused, S3 unreachable, OTLP endpoint returned non-2xx. Retries with backoff, up to the webhook’s max_retries.

A timeout or a stopped sparrow-sinks is also retried, so a restart loses nothing. Retry failed deliveries from the UI or with POST /v1/consumers/{consumer}/deliveries:retry.

Sends each delivery as one plain-text email, to every address in to.

Before you start: have an SMTP server that accepts mail from your from address, and its username and password (most providers: Mailgun, SES, Postmark, your own relay).

Field Required Default Meaning
smtp.host yes SMTP server host name.
smtp.port yes Usually 587. Port 465 (TLS from the first byte) isn’t supported; use 587 with starttls.
smtp.username no Login. No login is attempted when empty.
smtp.password no Password for username.
smtp.starttls no false Upgrade the connection with STARTTLS. Needed to log in to anything but localhost.
from yes Sender address.
to yes List of recipients. All of them get the same email.
subject_template no [sparrow] {{.event_name}} Subject, a Go template.
body_template no event name, ID, time, attempt and the indented payload Body, a Go template.
sinks.yaml
webhook_secret: whsec_...
email:
smtp:
host: smtp.mailgun.org
port: 587
username: postmaster@mg.example.com
password: your-smtp-password
starttls: true
from: alerts@example.com
to: [ops@example.com]
subject_template: "Order {{.payload.order_id}} paid"

What arrives, with the default templates, for an order.paid event:

Subject: [sparrow] order.paid
Event: order.paid
Event ID: 9fab6d74-baa0-45cd-af80-7a63ccdc08a5
Timestamp: 2026-10-08T14:13:05Z
Attempt: 1
Payload:
{
"order_id": "ord_9",
"total": 12.5
}

Good to know:

  • The templates see .event_name, .event_id, .timestamp (the delivery time), .attempt, .version, .payload (so .payload.order_id works) and .payload_pretty (the payload as indented JSON). They’re plain Go templates: the helper functions of subscription transforms aren’t available, and a missing field renders as <no value> instead of failing.
  • A template error is a 502, so Sparrow retries a delivery that can never succeed until its retries run out. Check templates with one test event first.
  • Retries can send the same email twice if the SMTP server accepted it but the connection dropped before the sink saw the reply.

Writes each delivery as one object: the envelope exactly as Sparrow sent it, with content type application/json. Works with AWS S3 and any S3-compatible store (MinIO, Cloudflare R2).

Before you start: create the bucket, and give the sink credentials that can s3:PutObject into it. Credentials come from the standard AWS chain: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, a shared profile, or an instance or pod role.

Field Required Default Meaning
bucket yes Bucket name.
region no from the AWS chain (AWS_REGION) Bucket region.
prefix no none Prepended to every key, e.g. events/. Include the trailing /.
endpoint no AWS Set it for MinIO or R2, e.g. http://minio.internal:9000. Turns on path-style addressing.
sinks.yaml
webhook_secret: whsec_...
s3:
endpoint: http://minio.internal:9000 # omit for AWS
region: us-east-1
bucket: sparrow-events
prefix: events/
Terminal window
export AWS_ACCESS_KEY_ID=minioadmin AWS_SECRET_ACCESS_KEY=minioadmin
sparrow-sinks --config sinks.yaml

What arrives: an object at {prefix}{event_name}/{YYYY}/{MM}/{DD}/{event_id}.json, for example events/order.paid/2026/10/08/9fab6d74-baa0-45cd-af80-7a63ccdc08a5.json, holding the envelope:

{"version":"1","event_id":"9fab6d74-baa0-45cd-af80-7a63ccdc08a5","event_name":"order.paid","timestamp":"2026-10-08T14:13:05Z","attempt":1,"payload":{"order_id":"ord_9","total":12.5}}

The layout partitions by event name and date, which suits Athena, DuckDB or ClickHouse queries over the bucket.

Good to know: the date in the key is the delivery date, not when the event was pushed. A retry on the same day overwrites the object; a retry after midnight UTC writes a second object under the next date.

Exports each delivery as one OpenTelemetry log record over OTLP/HTTP (JSON), so events show up in any OTel backend: Grafana Loki, Elastic, Datadog, Honeycomb, or a Collector that forwards to them. It sends logs, not traces.

Before you start: have an OTLP/HTTP endpoint (port 4318 on a Collector), and any auth header your vendor requires.

Field Required Default Meaning
endpoint yes http(s)://host:port. With no path, /v1/logs is added. A vendor URL with its own path is used as-is.
headers no none Extra request headers, e.g. Authorization: Bearer ....
service_name no sparrow The resource’s service.name.
sinks.yaml
webhook_secret: whsec_...
otlp:
endpoint: http://otel-collector:4318
headers:
Authorization: "Bearer your-token"
service_name: sparrow-events

What arrives: one log record per delivery. The body is the event payload as a JSON string; the event ID, name and attempt are attributes; severity is INFO; the record time is the delivery time.

Request body the OTLP endpoint receives
{
"resourceLogs": [{
"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "sparrow"}}]},
"scopeLogs": [{
"scope": {"name": "sparrow-sinks"},
"logRecords": [{
"timeUnixNano": "1791468926000000000",
"severityNumber": 9,
"severityText": "INFO",
"body": {"stringValue": "{\"order_id\":\"ord_9\",\"total\":12.5}"},
"attributes": [
{"key": "sparrow.event_id", "value": {"stringValue": "7b95ffda-0c44-4b4a-94c1-79304f979fd9"}},
{"key": "sparrow.event_name", "value": {"stringValue": "order.created"}},
{"key": "sparrow.attempt", "value": {"intValue": "1"}}
]
}]
}]
}]
}

Good to know: the request times out after 15 seconds, which counts as a 502; Sparrow retries it, so a slow endpoint can receive the same record twice.

  1. Register the event type and a webhook for the email sink (see Before you start), and copy its webhook_secret.

  2. Write sinks.yaml with that secret and the email: section from email, then start the sink:

    Terminal window
    sparrow-sinks --config sinks.yaml

    It logs email sink enabled path=/sinks/email and sparrow-sinks listening addr=:8788.

  3. Push an event:

    Terminal window
    curl -X POST 'http://localhost:8080/v1/consumers/default/events?event=order.paid' \
    -H 'Content-Type: application/json' \
    -d '{"payload": {"order_id": "ord_9", "total": 12.5}}'

    The sink logs delivered sink=email event_id=... and the email reaches every address in to. If it doesn’t, the delivery in Sparrow shows the sink’s answer: 401, 422 or 502 (see the table above).