Recipes
A recipe connects a Sparrow webhook to a service that expects its own payload format, such as a Slack message or a SendGrid email. It fills in the destination URL and headers and a transform template that turns each event into the body that service accepts. Sparrow renders the template on every delivery, so you keep retries, signing and delivery history, and there is no extra service to run.
Pick a recipe
Section titled “Pick a recipe”| Recipe | Sends each event as | You need from the service | Good for |
|---|---|---|---|
| slack | A Block Kit message in one channel | An incoming webhook URL | Team visibility |
| discord | An embed in one channel | A channel webhook URL | Team visibility |
| ntfy | A push notification on your phone or desktop | A topic name (and a server, if self-hosted) | Personal or small-team alerts |
| pagerduty | A triggered alert that can page on-call | An Events API v2 integration key | Paging on critical events |
| sendgrid | An email | An API key and a verified sender | Health alert emails, email notifications |
| clickhouse | A row in a table | An HTTP endpoint, a user and a table | An event archive for analytics |
| cloudevents | A CloudEvents 1.0 JSON event | A receiver URL | Knative, Argo Events, Dapr, or your own service |
| twilio | An SMS to one number | Account SID, Auth Token, a Twilio number | Text alerts |
Every recipe is built into the sparrow CLI: sparrow recipes lists them,
and sparrow recipes show <name> explains one’s inputs.
To preview what one sends before you apply it, use the
Recipe Workbench.
Apply a recipe
Section titled “Apply a recipe”From the dashboard: on Register webhook, open Start from a recipe, pick one, fill in its inputs, then choose the events.
From the CLI:
sparrow use slack \ --param webhook_url=https://hooks.slack.com/services/T000/B000/XXX \ --event order.created --event order.refunded \ --label env=prod| Flag | Meaning |
|---|---|
--param name=value |
A recipe input (listed under each recipe below). On a terminal the CLI prompts for any you leave out; elsewhere it names every missing required one. |
--event name |
An event type to deliver; at least one is required. Repeat it for several; each one gets its own subscription. |
--label key=value |
Only deliver events carrying this label. |
--consumer name |
The consumer to register the webhook under (a global flag; defaults to your CLI config). Use _sparrow for Sparrow’s own alert events. |
--file path |
Apply your own recipe file, or override a built-in one. |
--dry-run |
Show what would be created, and the body the first event’s sample would deliver, without changing anything. |
--update |
Re-apply to the webhook that already exists for the same destination (a consumer has one webhook per URL), instead of failing. |
Applying a recipe only creates a webhook and its subscriptions through the API. Nothing runs on your machine afterwards. The recipe is validated first, with its template rendered against the event type’s registered sample payload, and nothing is created if that fails.
What every recipe has in common
Section titled “What every recipe has in common”- The destination only receives the transformed body. Each recipe marks its webhook as requires a transform. Sparrow refuses a subscription on it without a template, and never sends the plain Sparrow envelope there.
- Template values. Templates see
event_id,event_name,payload,attempt(1 on the first try) andtimestamp.timestampis when this delivery attempt was rendered, not when the event was pushed, so a retry carries a later time. - Retries are re-rendered. A retry renders the template again with the next
attemptnumber. Recipes that need retries to be recognized as the same event useevent_id(PagerDuty’sdedup_key, CloudEvents’id). - Template failures are visible. If a template fails to render, the delivery
fails with
template_errorand nothing is sent. See When a template fails. - Secrets are encrypted. Inputs that become
secret_headers(API keys, passwords) are encrypted at rest and masked when you read the webhook back. Inputs that end up in the URL, in a plain header, or in the template are stored as plain text, and each recipe below says where its inputs go.
Posts each event to one Slack channel. The message shows the event name as a header, the event ID, time and attempt number, and the payload as a code block (cut off at about 2,900 characters to stay inside Slack’s block limit).
Before you start: in Slack, create an app with Incoming Webhooks turned on, add a webhook to the target channel, and copy its URL. One URL posts to one channel. For a second channel, apply the recipe again with that channel’s URL.
| Input | Required | What to enter |
|---|---|---|
webhook_url |
yes | The incoming webhook URL, https://hooks.slack.com/services/.... Stored as the webhook URL. |
sparrow use slack \ --param webhook_url=https://hooks.slack.com/services/T00/B00/X123 \ --event user.signup --event organization.upgradedRequest body Slack receives
{ "blocks": [ {"type": "header", "text": {"type": "plain_text", "text": "order.created", "emoji": true}}, {"type": "section", "fields": [ {"type": "mrkdwn", "text": "*Event ID:*\nevt_0195c2a1"}, {"type": "mrkdwn", "text": "*Timestamp:*\n2026-01-02T03:04:05Z"}, {"type": "mrkdwn", "text": "*Attempt:*\n1"} ]}, {"type": "section", "text": {"type": "mrkdwn", "text": "```{\"amount\":1999,\"order_id\":\"ord_42\"}```"}} ]}Good to know: the webhook URL is the only credential, so anyone who has it can post to the channel. To show specific payload fields instead of the raw JSON, edit the subscription’s template from the webhook page.
discord
Section titled “discord”Posts each event to one Discord channel as an embed: the event name as the title, the payload as a JSON code block (cut off at about 4,000 characters), and the delivery time.
Before you start: in Discord, open the channel’s Edit Channel → Integrations → Webhooks, create a webhook, and copy its URL.
| Input | Required | What to enter |
|---|---|---|
webhook_url |
yes | The channel webhook URL, https://discord.com/api/webhooks/.... Stored as the webhook URL. |
sparrow use discord \ --param webhook_url=https://discord.com/api/webhooks/123/abc \ --event deployment.completedRequest body Discord receives
{ "embeds": [ { "title": "order.created", "description": "```json\n{\"amount\":1999,\"order_id\":\"ord_42\"}\n```", "timestamp": "2026-01-02T03:04:05Z" } ]}Sends each event as a push notification to an ntfy topic. Anyone subscribed to the topic in the ntfy app sees the event name as the title, then a line with the event ID, attempt and time, followed by the payload.
Before you start: pick a topic name and subscribe to it in the ntfy app.
On the public ntfy.sh server anyone who knows a topic name can read it, so
choose one that’s hard to guess, or use your own server.
| Input | Required | What to enter |
|---|---|---|
server_url |
no | The ntfy server. Default https://ntfy.sh. |
topic |
yes | The topic name, e.g. acme-orders-7f3k. Stored in the template. |
sparrow use ntfy --param topic=acme-orders-7f3k --event order.createdRequest body ntfy receives
{ "topic": "acme-orders-7f3k", "title": "order.created", "message": "event evt_0195c2a1, attempt 1 at 2026-01-02T03:04:05Z\n\n{\"amount\":1999,\"order_id\":\"ord_42\"}", "tags": ["incoming_envelope"]}Good to know: the recipe sends no access token, so it can’t publish to a protected topic on a server that requires login.
pagerduty
Section titled “pagerduty”Triggers a PagerDuty alert for each event through the Events API v2. Whether it pages someone is decided by the PagerDuty service’s escalation policy.
Before you start: in PagerDuty, open the service, go to Integrations → Add an integration → Events API V2, and copy the Integration Key.
| Input | Required | What to enter |
|---|---|---|
routing_key |
yes | The 32-character integration key. Stored in the template, not encrypted. |
severity |
no | Severity for events whose payload has no severity field: critical, error, warning or info. Default error. |
sparrow use pagerduty \ --param routing_key=R0UT1NGKEY0000000000000000000000 \ --event system.database_down --event payment.gateway_error \ --label env=productionWhat the alert contains:
- Summary:
Sparrow event: <event name>. - Severity: the payload’s
severityfield if it has one, otherwise theseverityinput. - Details: the whole payload, under Custom Details.
- Deduplication: the event ID is the
dedup_key, so retries of one event update the same alert instead of opening new ones.
Request body PagerDuty receives
{ "routing_key": "R0UT1NGKEY0000000000000000000000", "event_action": "trigger", "dedup_key": "evt_0195c2a1", "payload": { "summary": "Sparrow event: order.created", "source": "sparrow", "severity": "error", "timestamp": "2026-01-02T03:04:05Z", "custom_details": {"amount": 1999, "order_id": "ord_42"} }}Good to know:
- The recipe only triggers alerts and never resolves them. Resolve them in
PagerDuty, or write a second subscription whose template sends
"event_action": "resolve"with the samededup_key. - A payload
severityother than the four allowed values is rejected by PagerDuty, so the delivery fails. Send one of those values, or drop the field. - The integration key ends up in the subscription’s template, which is stored unencrypted. Treat access to Sparrow’s API as access to the key.
sendgrid
Section titled “sendgrid”Sends an email through SendGrid’s Mail Send API. It’s built mainly for Sparrow’s health alert emails, and also works for your own events.
Before you start:
- In SendGrid, create an API key under Settings → API Keys. Restricted access with only Mail Send turned on is enough.
- Verify the address you’ll send from: Settings → Sender Authentication, either as a single sender or by authenticating your domain. SendGrid rejects mail from an unverified sender.
| Input | Required | What to enter |
|---|---|---|
api_key |
yes | The SendGrid API key, SG..... Sent as Authorization: Bearer, encrypted at rest. |
from_email |
yes | The verified sender address. The default alerts@example.com is a placeholder and is rejected. |
from_name |
no | Sender display name. Default Sparrow. Avoid double quotes: the value is placed in the template as-is. |
default_recipient |
yes | Who gets an email when the event names no recipients. See the two uses below. |
Use 1: health alert emails
Section titled “Use 1: health alert emails”Sparrow emits sparrow.webhook.* events under its internal _sparrow
consumer. Each one carries alert_recipients, the addresses opted in through
alert configs.
Register the recipe under _sparrow and subscribe it to those events:
sparrow --consumer _sparrow use sendgrid \ --param api_key=$SENDGRID_API_KEY \ --param from_email=alerts@yourdomain.com \ --param from_name="Sparrow Alerts" \ --param default_recipient=ops@yourdomain.com \ --event sparrow.webhook.health_changed \ --event sparrow.webhook.delivery_failed \ --event sparrow.webhook.disabledOne delivery emails every opted-in recipient, each separately, so nobody sees
the others’ addresses. If no alert config matches, the email goes to
default_recipient, which makes it a catch-all for your ops inbox. The emails
are plain text:
| Event | Subject | Body |
|---|---|---|
sparrow.webhook.health_changed |
Sparrow: webhook for <consumer> is now degraded (or ... recovered) |
Webhook ID and URL, old → new health |
sparrow.webhook.delivery_failed |
Sparrow: delivery to <consumer> failed permanently |
Webhook, delivery ID, attempts, error message and category |
sparrow.webhook.disabled |
Sparrow: webhook for <consumer> was auto-disabled |
Webhook and the reason it was paused |
Use 2: emails for your own events
Section titled “Use 2: emails for your own events”Register the recipe under your own consumer and pick your events. Every
email goes to default_recipient, with the subject Sparrow event: <event name> and a body listing the event ID, attempt, time and the payload as
JSON. To write your own subject and body, edit the subscription’s template after
applying.
sparrow use sendgrid \ --param api_key=$SENDGRID_API_KEY \ --param from_email=orders@yourdomain.com \ --param default_recipient=sales@yourdomain.com \ --event order.createdRequest body SendGrid receives (health alert, one recipient)
{ "personalizations": [{"to": [{"email": "ops@acme.example.com"}]}], "from": {"email": "alerts@yourdomain.com", "name": "Sparrow Alerts"}, "subject": "Sparrow: webhook for acme is now degraded", "content": [{"type": "text/plain", "value": "Webhook 7c9e... (https://api.acme.example.com/hooks) health changed: healthy -> degraded"}]}clickhouse
Section titled “clickhouse”Inserts each event as one row into a ClickHouse table over the HTTP interface
(INSERT ... FORMAT JSONEachRow).
Before you start: create the table. The recipe writes four String columns:
CREATE TABLE sparrow_events( event_id String, event_name String, timestamp String, -- delivery time, RFC 3339 payload String -- the event payload as JSON text)ENGINE = ReplacingMergeTreeORDER BY event_id;ReplacingMergeTree ordered by event_id collapses the duplicate row that
appears if ClickHouse stored an insert but the response was lost and Sparrow
retried it. Query with FINAL, or argMax, for exact counts. Read payload
fields with JSONExtractString(payload, 'order_id') and similar.
| Input | Required | What to enter |
|---|---|---|
base_url |
yes | The HTTP endpoint, e.g. https://ch.example.com:8443. |
table |
yes | The table, e.g. sparrow_events or analytics.sparrow_events. Goes into the URL, so use plain names. |
user |
yes | A ClickHouse user with INSERT on the table. Sent as the X-ClickHouse-User header. |
password |
yes | That user’s password. Sent as X-ClickHouse-Key, encrypted at rest. |
sparrow use clickhouse \ --param base_url=https://ch.example.com:8443 \ --param table=analytics.sparrow_events \ --param user=sparrow_ingest --param password=$CH_PASSWORD \ --event order.created --event payment.refundedRow ClickHouse receives
{"event_id": "evt_0195c2a1", "event_name": "order.created", "timestamp": "2026-01-02T03:04:05Z", "payload": "{\"amount\":1999,\"order_id\":\"ord_42\"}"}Good to know: timestamp is when the row was delivered, not when the event
happened. For the event’s own time, include it in the payload.
cloudevents
Section titled “cloudevents”Delivers each event as a CloudEvents 1.0 event in
structured mode (Content-Type: application/cloudevents+json), so any
CloudEvents receiver can consume it: a Knative broker, Argo Events, Dapr, or
your own service using a CloudEvents SDK.
| Input | Required | What to enter |
|---|---|---|
target_url |
yes | The receiver’s URL. |
source |
no | The source attribute naming this producer, a URI reference. Default /sparrow. |
sparrow use cloudevents \ --param target_url=https://broker.example.com/default/events \ --event order.createdHow Sparrow’s fields map to CloudEvents attributes:
| CloudEvents | Comes from |
|---|---|
id |
The Sparrow event ID. Retries keep it, so receivers can deduplicate on id + source. |
type |
The event name, e.g. order.created. |
source |
The source input. |
time |
The delivery time (later on retries). |
data |
The event payload. |
Request body the receiver gets
{"specversion": "1.0", "id": "evt_0195c2a1", "source": "/sparrow", "type": "order.created", "time": "2026-01-02T03:04:05Z", "datacontenttype": "application/json", "data": {"amount": 1999, "order_id": "ord_42"}}twilio
Section titled “twilio”Sends one SMS per event to a single phone number through the Twilio Messages
API. The text is short and has no payload, for example:
Sparrow order.created (event evt_0195c2a1, attempt 1) at 2026-01-02T03:04:05Z.
Before you start:
-
From the Twilio Console, copy your Account SID (
AC...) and Auth Token. -
Have a Twilio phone number to send from. Trial accounts can only text numbers you have verified in Twilio.
-
Build the
basic_authinput from the two values:Terminal window printf '%s:%s' "$TWILIO_ACCOUNT_SID" "$TWILIO_AUTH_TOKEN" | base64
| Input | Required | What to enter |
|---|---|---|
account_sid |
yes | The Account SID. Goes into the URL. |
basic_auth |
yes | The base64 value from step 3. Sent as Authorization: Basic, encrypted at rest. |
from_number |
yes | Your Twilio number, country code first, digits only, no +: 15551230000. |
to_number |
yes | The recipient, in the same format. |
sparrow use twilio \ --param account_sid=$TWILIO_ACCOUNT_SID \ --param basic_auth=$(printf '%s:%s' "$TWILIO_ACCOUNT_SID" "$TWILIO_AUTH_TOKEN" | base64) \ --param from_number=15551230000 --param to_number=15559876543 \ --event system.database_downGood to know: one webhook texts one number. To reach several people, apply
the recipe once per number. To include payload fields in the text, edit the
template’s Body= part and keep it passed through urlencode.
Request body Twilio receives (form-encoded)
To=%2B15559876543&From=%2B15551230000&Body=Sparrow+order.created+%28event+evt_0195c2a1%2C+attempt+1%29+at+2026-01-02T03%3A04%3A05ZWriting your own
Section titled “Writing your own”A recipe is one file, satellites/recipes/<name>.yaml, schema version 1:
version: 1name: myservice # must match the filenamedescription: One-line human descriptionparams: # values supplied at apply time via --param - name: api_token prompt: "MyService API token" required: true secret: true # marks the value as sensitive (for UI hints) - name: api_url prompt: "MyService ingest URL" required: true default: https://api.example.com/ingest must_override_default: true # the user must change this from the defaultwebhook: requires_transform: true # Sparrow refuses subscriptions without a template url: '{{param "api_url"}}' headers: {Content-Type: application/json} secret_headers: # envelope-encrypted at rest, masked on read Authorization: 'Bearer {{param "api_token"}}'guidance: | # what an ideal message looks like (advice, not a rule) Lead with what happened in plain words; a short title, 2-6 key facts, a link.subscription: transform_template: | {"title": {{.event_name | json}}, "body": {{.payload | json}}}Every shipped recipe sets webhook.requires_transform: true, so Sparrow
refuses any subscription on that webhook without an enabled transform template
and never sends the default envelope to the destination.
Param fields beyond name, prompt (a short label), required, and default:
help– one sentence on what the value is and where to find it.example– a sample value; the UI shows it as the input’s placeholder.enum– the only accepted values; the UI renders a select. Adefaultmust be one of them.docs_url– the destination’s documentation for this value.secret– hints that the value is sensitive (e.g. an API key).activation_required– the value must be obtained from the destination service before applying (e.g. a SendGrid API key or verified sender).must_override_default– the user must change the default value; applying with the original default is rejected.
A recipe can also name the consumer it is meant for, with a consumer block
(name and note). The UI shows the note and offers to switch to that
consumer: the shipped sendgrid recipe uses it, because its alert emails only
work under _sparrow.
Validating a recipe
Section titled “Validating a recipe”go test ./satellites/recipes/ checks every shipped recipe. For a draft, or a
local recipe outside the repo, sparrow recipes validate --file draft.yaml
(or the sparrow mcp server’s
validate_recipe tool) runs the same checks without registering anything,
and exits non-zero on errors: param tokens and enums, a strict render of the template with params
substituted (missing payload keys are errors, as on a subscription), valid JSON
when the Content-Type is JSON, and an http(s) URL once real param values are
given. Keys outside the schema, such as a misspelled requires_transform, and
the catalog’s shipping rules (description, guidance, param help) come back as
warnings. sparrow use and apply_recipe run the same validation and
refuse to create anything when it fails.
guidance describes what an ideal message for the destination looks like:
what goes first, length, structure, tone, the destination’s own conventions
(Slack’s fallback text, SMS segments, PagerDuty dedup keys), and a short
rendered example. It is advice, not a rule, and nothing validates against it.
AI template drafting gives it to the model so a draft reads well rather than
only rendering; the user’s instructions and receiver example still win. Every
shipped recipe has one.
{{param "x"}} tokens in webhook.url, header values, secret_headers values,
and the template are
replaced by the CLI at apply time via plain string substitution. The
substituted template is registered on the subscription and rendered per
delivery with .event_id, .event_name, .timestamp (RFC3339), .attempt,
and .payload. Helpers like json, printf, upper, and ellipsis are
available — see template functions.
Three rules keep templates robust:
- Quote every interpolated value through
json(e.g.{{.event_name | json}}) so quotes or newlines in payloads can’t corrupt the output. - Read fields that may be absent with
digorindex({{ dig "severity" "error" .payload }}): a missing field fails the render. - Iterate locally with
sparrow template test, which renders the template entirely client-side (no API call) against a synthetic sample context, without creating anything.