Skip to content

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.

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.

From the dashboard: on Register webhook, open Start from a recipe, pick one, fill in its inputs, then choose the events.

From the CLI:

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

  • 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) and timestamp. timestamp is 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 attempt number. Recipes that need retries to be recognized as the same event use event_id (PagerDuty’s dedup_key, CloudEvents’ id).
  • Template failures are visible. If a template fails to render, the delivery fails with template_error and 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.
Terminal window
sparrow use slack \
--param webhook_url=https://hooks.slack.com/services/T00/B00/X123 \
--event user.signup --event organization.upgraded
Request 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.

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.
Terminal window
sparrow use discord \
--param webhook_url=https://discord.com/api/webhooks/123/abc \
--event deployment.completed
Request 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.
Terminal window
sparrow use ntfy --param topic=acme-orders-7f3k --event order.created
Request 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.

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.
Terminal window
sparrow use pagerduty \
--param routing_key=R0UT1NGKEY0000000000000000000000 \
--event system.database_down --event payment.gateway_error \
--label env=production

What the alert contains:

  • Summary: Sparrow event: <event name>.
  • Severity: the payload’s severity field if it has one, otherwise the severity input.
  • 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 same dedup_key.
  • A payload severity other 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.

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:

  1. In SendGrid, create an API key under Settings → API Keys. Restricted access with only Mail Send turned on is enough.
  2. 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.

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:

Terminal window
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.disabled

One 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

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.

Terminal window
sparrow use sendgrid \
--param api_key=$SENDGRID_API_KEY \
--param from_email=orders@yourdomain.com \
--param default_recipient=sales@yourdomain.com \
--event order.created
Request 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"}]
}

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 = ReplacingMergeTree
ORDER 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.
Terminal window
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.refunded
Row 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.

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.
Terminal window
sparrow use cloudevents \
--param target_url=https://broker.example.com/default/events \
--event order.created

How 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"}}

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:

  1. From the Twilio Console, copy your Account SID (AC...) and Auth Token.

  2. Have a Twilio phone number to send from. Trial accounts can only text numbers you have verified in Twilio.

  3. Build the basic_auth input 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.
Terminal window
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_down

Good 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%3A05Z

A recipe is one file, satellites/recipes/<name>.yaml, schema version 1:

version: 1
name: myservice # must match the filename
description: One-line human description
params: # 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 default
webhook:
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. A default must 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.

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:

  1. Quote every interpolated value through json (e.g. {{.event_name | json}}) so quotes or newlines in payloads can’t corrupt the output.
  2. Read fields that may be absent with dig or index ({{ dig "severity" "error" .payload }}): a missing field fails the render.
  3. Iterate locally with sparrow template test, which renders the template entirely client-side (no API call) against a synthetic sample context, without creating anything.