Skip to content

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.

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:

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

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.

You don’t have to guess. Test any template against a sample event:

  1. List the available helpers:

    Terminal window
    curl http://localhost:8080/v1/template-functions
  2. 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 from GET /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"}
    }'
  3. 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 zero to render missing fields as <no value>, like a subscription with template_missing_key: zero.

Each example shows the incoming event, the template you’d set on the subscription, and the delivered result.

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.

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.

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.

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.

  • 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 range at 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 answers 503.
  • Why Go templates and not JavaScript? See Why Sparrow for the trade-off.

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

  • 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.