SATELLITE WORKBENCH

Satellite Recipe Workbench

Compose the message, and the workbench writes the Sparrow transform template for you. Preview exactly what the destination receives, then apply it with one CLI command.

SendGrid Email: Send events as email via the SendGrid v3 Mail Send API

1. Sample event

The event Sparrow delivers. Pick a preset or paste your own payload — its fields become the variable chips below.

Event name

Attempt

Payload JSON

✓ Valid JSON

{
  "alert_recipients": [
    {
      "email": "devops-team@acme.com"
    },
    {
      "email": "oncall@acme.com"
    }
  ],
  "consumer": "billing-service",
  "webhook_id": "wh_01h8x9p3",
  "url": "https://api.acme.com/v1/webhooks/billing",
  "old_health": "healthy",
  "new_health": "degraded"
}

2. Compose the email

Chips insert the event field at the cursor of the last text field you clicked into.

One email per address in the list — recipients never see each other. Falls back to the default_recipient parameter when the list is missing. Second box: the field on each item holding the address (empty for a list of plain strings).

Subject

Body

3. Recipe parameters

Asked once when you apply the recipe; secrets are envelope-encrypted at rest.

SendGrid API key

Verified sender email address

Sender display name

Recipient for events without payload.alert_recipients (e.g. team@acme.com)

What SendGrid Email receives

sendgrid

Subject: Sparrow: webhook for billing-service is now degraded

From: Sparrow Webhooks <alerts@example.com>

To: devops-team@acme.com, oncall@acme.com

Webhook wh_01h8x9p3 (https://api.acme.com/v1/webhooks/billing) health changed: healthy -> degraded

Rendered request body

Rendered request body sent to api.sendgrid.com

{
  "personalizations": [{"to": [{"email": "devops-team@acme.com"}]},{"to": [{"email": "oncall@acme.com"}]}],
  "from": {"email": "alerts@example.com", "name": "Sparrow Webhooks"},
  "subject": "Sparrow: webhook for billing-service is now degraded",
  "content": [{"type": "text/plain", "value": "Webhook wh_01h8x9p3 (https://api.acme.com/v1/webhooks/billing) health changed: healthy -> degraded"}]
}

Preview is rendered by a simplified in-browser engine; the server uses Go's text/template.

Go transform template (what Sparrow stores)

{
  "personalizations": [{{if .payload.alert_recipients}}{{range $i, $r := .payload.alert_recipients}}{{if $i}},{{end}}{"to": [{"email": {{$r.email | json}}}]}{{end}}{{else}}{"to": [{"email": "{{param "default_recipient"}}"}]}{{end}}],
  "from": {"email": "{{param "from_email"}}", "name": "{{param "from_name"}}"},
  "subject": {{printf "Sparrow: webhook for %v is now %v" .payload.consumer .payload.new_health | json}},
  "content": [{"type": "text/plain", "value": {{printf "Webhook %v (%v) health changed: %v -> %v" .payload.webhook_id .payload.url .payload.old_health .payload.new_health | json}}}]
}

Apply with the Sparrow CLI

Registers this recipe on your Sparrow server. To use a customized template, save the generated template above into your own recipe file first.

sparrow use sendgrid \
  --param api_key="<secret>" \
  --param from_email="alerts@example.com" \
  --param from_name="Sparrow Webhooks" \
  --param default_recipient="team@acme.com" \
  --event sparrow.webhook.health_changed

4. How to set up SendGrid Email

Where the credentials above come from, per the official docs.

Settings → API Keys → Create API Key; pick Restricted Access and enable Mail Send.
Copy the key immediately (shown only once) into api_key.
Settings → Sender Authentication → verify a Single Sender (or authenticate your domain).
Use that verified address as from_email; from_name is the display name.

SendGrid API keys & sender verification →