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.
Pick a sink
Section titled “Pick a sink”| Sink | Path on sparrow-sinks |
Each delivery becomes | You need |
|---|---|---|---|
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.
Sink or recipe?
Section titled “Sink or recipe?”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 and run
Section titled “Install and run”Install the release binary (macOS and Linux) with the install script:
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh -s -- -c sinkssparrow-sinks --config sinks.yamlOr 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:
FROM alpine:3.22RUN apk add --no-cache curl \ && curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh \ | sh -s -- -c sinks -b /usr/local/binENTRYPOINT ["sparrow-sinks", "--config", "/etc/sparrow/sinks.yaml"]docker build -t sparrow-sinks .docker run -v "$(pwd)/sinks.yaml:/etc/sparrow/sinks.yaml:ro" -p 8788:8788 sparrow-sinksUse it as a Go library
Section titled “Use it as a Go library”Each sink is a Go package you can mount on your own server instead of running
sparrow-sinks:
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 }))Before you start
Section titled “Before you start”-
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"}' -
Let Sparrow reach the sink. Sparrow refuses delivery URLs on
localhostand private networks by default. Ifsparrow-sinksruns on a private network, list that network inSPARROW_ALLOWED_NETWORKSon the Sparrow server (for example10.20.0.0/16). If it runs on the same machine (localhost), start the server withSPARROW_ALLOW_PRIVATE_NETWORKS=true, which is meant for development. -
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 copysigning_public_keyinstead (it isn’t secret and stays readable on everyGET). The sink then verifies the Ed25519 signature with that public key. -
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.
Configuration
Section titled “Configuration”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. |
listen: :8788email: 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-1How 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. |
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.paidEvent ID: 9fab6d74-baa0-45cd-af80-7a63ccdc08a5Timestamp: 2026-10-08T14:13:05ZAttempt: 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_idworks) 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. |
webhook_secret: whsec_...s3: endpoint: http://minio.internal:9000 # omit for AWS region: us-east-1 bucket: sparrow-events prefix: events/export AWS_ACCESS_KEY_ID=minioadmin AWS_SECRET_ACCESS_KEY=minioadminsparrow-sinks --config sinks.yamlWhat 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. |
webhook_secret: whsec_...otlp: endpoint: http://otel-collector:4318 headers: Authorization: "Bearer your-token" service_name: sparrow-eventsWhat 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.
Worked example: email on every paid order
Section titled “Worked example: email on every paid order”-
Register the event type and a webhook for the email sink (see Before you start), and copy its
webhook_secret. -
Write
sinks.yamlwith that secret and theemail:section from email, then start the sink:Terminal window sparrow-sinks --config sinks.yamlIt logs
email sink enabled path=/sinks/emailandsparrow-sinks listening addr=:8788. -
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 into. If it doesn’t, the delivery in Sparrow shows the sink’s answer:401,422or502(see the table above).