Transforming Payloads
New to Sparrow? This guide shows you how to change the shape of a webhook payload before it’s delivered — no code, no proxy service, just a small template you write once per subscription.
What is a transform, and why would I want one?
Section titled “What is a transform, and why would I want one?”A webhook payload is just a chunk of JSON. The problem is that the system Sparrow delivers to rarely wants the exact JSON your event started with:
- Slack wants a
{"text": "..."}message, not your raw event. - Your billing system wants amounts in cents, but your event has dollars.
- A legacy endpoint wants a flat object, but your event is deeply nested.
- A partner should only see three fields, not your entire internal record.
A transform solves this. You attach a small template to a subscription, and Sparrow runs your event through it to produce the body that actually gets sent.
Where the transform lives
Section titled “Where the transform lives”A transform is four fields on a subscription (the link between a webhook
and one event type). Set them when you create the subscription, or later with a
PATCH:
curl -X PATCH http://localhost:8080/v1/consumers/default/subscriptions/{subscription_id} \ -H 'Content-Type: application/json' \ -d @- <<'JSON'{ "transform_enabled": true, "transform_template": "{{ dict \"text\" (printf \"Order %s: %v\" .payload.order_id .payload.total) | json }}", "on_transform_error": "fail", "template_missing_key": "error"}JSON| Field | Meaning |
|---|---|
transform_enabled |
true to send the rendered template instead of the standard envelope. false keeps the template stored but unused. |
transform_template |
The template. It’s a JSON string, so quotes inside it are escaped as \". The heredoc (-d @- <<'JSON') keeps the shell from touching anything else. |
on_transform_error |
fail (default) or fallback. See When a template fails. |
template_missing_key |
error (default) or zero. Same section. |
The response is the updated subscription. With the template above, an event
with payload {"order_id": "ord_7", "total": 12.5} is delivered as
{"text":"Order ord_7: 12.5"}.
Find the subscription ID with
GET /v1/consumers/{consumer}/subscriptions?webhook_id=..., or edit the
template in the UI: open the webhook, then the subscription’s Edit, which
opens a template editor with a live preview.
The mental model (read this first)
Section titled “The mental model (read this first)”A template receives your event and prints text. Whatever text it prints becomes the delivered body. Your event is available through these fields:
| Field | What it is |
|---|---|
.payload |
Your event’s data (the JSON you pushed) |
.event_name |
The event type, e.g. payment.succeeded |
.event_id |
Unique ID for this event |
.timestamp |
When this delivery attempt was rendered (RFC 3339 string), so a retry has a later time. For the event’s own time, put it in the payload |
.attempt |
Which delivery attempt this is |
So {{ .payload.customer.email }} reads the customer.email field out of your
event, and {{ .event_name }} prints the event type.
Try it before you ship it
Section titled “Try it before you ship it”You don’t have to guess. Test any template against a sample event:
-
List the available helpers:
Terminal window curl http://localhost:8080/v1/template-functions -
Test a template against an event type’s sample payload (returns the rendered output; it renders strictly, as a subscription does by default):
Terminal window curl -X POST http://localhost:8080/v1/subscriptions:testTemplate \-H 'Content-Type: application/json' \-d '{"event_name": "payment.succeeded","template": "{{ dict \"id\" .event_id \"amount\" .payload.amount | json }}"}'The sample is generated from the event type’s schema, so its values are placeholders. Add
"payload"to render against real data instead, such as a stored event’s payload fromGET /v1/consumers/{consumer}/events. The event type must still be registered, but it needs no schema:Terminal window curl -X POST http://localhost:8080/v1/subscriptions:testTemplate \-H 'Content-Type: application/json' \-d '{"event_name": "payment.succeeded","template": "{{ dict \"id\" .event_id \"amount\" .payload.amount | json }}","payload": {"amount": 4200, "currency": "EUR"}}' -
Or entirely offline with the CLI (no server round-trip; renders locally against a synthetic sample context instead of a stored event payload):
Terminal window sparrow template test partner.tmpl --payload '{"amount": 4200}'Add
--missing-key zeroto render missing fields as<no value>, like a subscription withtemplate_missing_key: zero.
Real-world examples
Section titled “Real-world examples”Each example shows the incoming event, the template you’d set on the subscription, and the delivered result.
1. Send only the fields a partner needs
Section titled “1. Send only the fields a partner needs”Problem: your event has 30 internal fields, but a partner should only see three.
Incoming .payload:
{ "id": "evt_123", "amount": 4200, "internal_notes": "…", "secret": "…" }Template:
{{ dict "id" .payload.id "amount" .payload.amount "event" .event_name | json }}Delivered:
{"amount":4200,"event":"payment.succeeded","id":"evt_123"}dict builds an object from "key" value pairs; json turns it into JSON.
2. Post a message to Slack
Section titled “2. Post a message to Slack”Problem: Slack’s Incoming Webhooks expect {"text": "..."}.
Incoming .payload:
{ "customer": { "name": "Ada" }, "amount": 4200, "currency": "usd" }Template:
{{ dict "text" (printf "%s paid %s %.2f" (dig "customer" "name" "Someone" .payload) (upper .payload.currency) (div .payload.amount 100)) | json }}Delivered:
{"text":"Ada paid USD 42.00"}Here dig safely reads customer.name (falling back to "Someone" if it’s
missing), div converts cents to dollars, and printf formats the sentence.
3. Convert dollars to cents for a billing system
Section titled “3. Convert dollars to cents for a billing system”Problem: your event has amounts in dollars; the target wants integer cents.
Incoming .payload:
{ "customer": { "id": "cus_9" }, "amount": 42.5, "currency": "usd" }Template:
{{ dict "user" (dig "customer" "id" "" .payload) "amount_cents" (toInt (mul .payload.amount 100)) "currency" .payload.currency | json }}Delivered:
{"amount_cents":4250,"currency":"usd","user":"cus_9"}mul multiplies, toInt drops the decimal so you get a clean integer.
4. Flatten a nested payload for a legacy endpoint
Section titled “4. Flatten a nested payload for a legacy endpoint”Problem: an old system wants a flat object, but your data is nested.
Incoming .payload:
{ "customer": { "id": "c1", "email": "ada@example.com" }, "order": { "total": 99.5 } }Template:
{{ dict "customer_id" (dig "customer" "id" "" .payload) "email" (dig "customer" "email" "" .payload) "total" (dig "order" "total" 0 .payload) | json }}Delivered:
{"customer_id":"c1","email":"ada@example.com","total":99.5}dig walks a path of keys and returns your default if any part is missing — so
one absent field never breaks the whole delivery.
5. Summarize a list of items
Section titled “5. Summarize a list of items”Problem: your event has an array of line items; you only want the SKUs.
Incoming .payload:
{ "items": [ { "sku": "A" }, { "sku": "B" }, { "sku": "C" } ] }Template:
{{ $skus := list }}{{ range .payload.items }}{{ $skus = append $skus .sku }}{{ end }}{{ dict "skus" $skus | json }}Delivered:
{"skus":["A","B","C"]}range loops over the array; append collects each SKU into a growing list.
6. Add a constant or computed field
Section titled “6. Add a constant or computed field”Problem: you want to pass the whole payload through, but tag it with extra metadata.
Template:
{{ merge .payload (dict "source" "sparrow" "delivered_at" .timestamp) | json }}Delivered: your original payload, plus "source" and "delivered_at"
(the time of this delivery attempt, e.g. "2026-10-08T14:21:05Z").
merge combines maps; later keys win, and the originals are left untouched.
7. Provide safe defaults for optional fields
Section titled “7. Provide safe defaults for optional fields”Problem: some events are missing optional fields, and you want sensible fallbacks instead of empty values.
Template:
{{ dict "name" (dig "customer" "name" "Guest" .payload) "plan" (default "free" (index .payload "plan")) | json }}dig covers missing nested keys. index reads a top-level key without failing
when it is absent, and default then covers a field that is missing or
present but empty.
Good to know
Section titled “Good to know”- Transforms run at delivery, on the way out. They don’t change what Sparrow stores or how it fans out — only the body each subscription receives.
- A template that fails is visible. See When a template fails.
- There are limits. Output is capped at 1 MB and execution at 5
seconds per transform. A render may also run at most 1,000,000 loop
iterations and template calls, and build at most 16 MB of strings and lists
along the way, and nest
rangeat most 3 levels deep, so a runaway template can’t stall a worker. When too many templates are rendering at once, a delivery waits and is retried later instead of failing, and a preview answers503. - Why Go templates and not JavaScript? See Why Sparrow for the trade-off.
When a template fails
Section titled “When a template fails”A template that does not parse, such as {{ .payload.id with no closing
braces or a call to a function that does not exist, is rejected with 400
when you save the subscription, so it never reaches a delivery. Saving only
parses the template; it does not render it, because whether a template fits
the payload is only known once an event arrives (use testTemplate above to
try it against a sample).
At delivery time a template fails when it reads a field the payload does not have (with the
default template_missing_key: error), calls a function with the wrong kind of
value, or exceeds the limits above. Two settings on the subscription decide
what happens.
| Setting | Values |
|---|---|
on_transform_error |
fail (default): nothing is sent. The delivery is marked failed with error category template_error, is not retried automatically, and keeps the error in template_error. fallback: the standard event envelope is sent instead, and the error is still recorded on the delivery. |
template_missing_key |
error (default): reading a missing field fails the template. zero: it prints <no value> and the delivery goes out. |
curl -X PATCH http://localhost:8080/v1/consumers/acme/subscriptions/{subscription_id} \ -H 'Content-Type: application/json' \ -d '{"on_transform_error": "fallback", "template_missing_key": "zero"}'A template error is a problem on the sending side, not with the receiving
system, so it never counts toward the webhook’s health and raises no health
alert. It is counted in the sparrow_template_errors_total metric.
To recover, fix the template, then retry: one delivery with
POST /v1/consumers/{consumer}/deliveries/{delivery_id}:retry, or all of them
by listing ?status=failed&error_category=template_error&prepare_retry=true
and starting a batch retry. Every attempt renders the subscription’s current
template, so the retry uses the fixed one. In the UI, filter Deliveries by the
Template Error category.
When an event type’s schema changes, Sparrow checks every subscription’s template against the new schema before the change is written; see Event Type Versions.
Where to go next
Section titled “Where to go next”- Template Functions reference — the full list of all 37 helpers with signatures and examples.
- Recipes — one-command webhook + transform setups for Slack, PagerDuty, SendGrid and more.