Technique
How to Transform a Webhook Payload Without Writing a Server
The service sending you a webhook chose its own JSON. The API you want to call expects different JSON. The usual fix is a small server whose only job is to rename fields. A template does the same work with nothing to host.
17 November 2026 · 4 min read
A template is the output with holes in it
You write the request body the destination wants. Wherever a value should come from the incoming webhook, you put its path in double braces. That is the whole idea.
Say a monitoring service sends this:
{
"alert": {
"id": "al_2041",
"title": "Checkout latency above 2s",
"severity": "critical",
"started_at": 1794835200,
"value": 2.41,
"tags": [
"checkout",
"eu-west"
]
},
"service": {
"name": "Storefront",
"owner": {
"email": " Ops@Example.com"
}
},
"links": [
{
"rel": "dashboard",
"href": "https://status.example.com/al_2041"
}
]
}And your incident API wants a flat object with different names. This is the template:
{
"summary": "[{{body.alert.severity | upper}}] {{body.alert.title}}",
"source": "{{body.service.name}}",
"value": "{{body.alert.value}}",
"tags": "{{body.alert.tags}}",
"tag_list": "{{body.alert.tags | join: \", \"}}",
"owner": "{{body.service.owner.email | trim | lower}}",
"started": "{{body.alert.started_at | iso}}",
"url": "{{body.links[0].href}}",
"runbook": "{{body.alert.runbook | default: \"https://wiki.example.com/runbooks\"}}",
"received_at": "{{request.timestamp}}"
}And this is what gets sent:
{
"summary": "[CRITICAL] Checkout latency above 2s",
"source": "Storefront",
"value": 2.41,
"tags": [
"checkout",
"eu-west"
],
"tag_list": "checkout, eu-west",
"owner": "ops@example.com",
"started": "2026-11-16T13:20:00.000Z",
"url": "https://status.example.com/al_2041",
"runbook": "https://wiki.example.com/runbooks",
"received_at": "2026-11-17T09:41:07.212Z"
}Four rules that explain the result
- A value that is exactly one placeholder keeps its type.
"{{body.alert.value}}"became the number2.41, not the text "2.41", and"{{body.alert.tags}}"became a real array. The quotation marks in the template are only there so the template itself is valid JSON. - A placeholder mixed with text becomes text.
summaryhas words around its placeholders, so the result is a string. - Missing values are explicit. The payload had no
runbook, so thedefaultfilter supplied one. Without a default, a missing value isnullin JSON and nothing at all inside text. - The output is always valid JSON. Values are placed into the structure, not pasted into a string. A title containing a quotation mark or a line break cannot break the payload.
Reaching into the request
| You write | You get |
|---|---|
body.alert.title | A field of the JSON body (or of a form-encoded body) |
body.links[0].href | An item of an array, by position |
body["user.name"] | A key that contains a dot or other punctuation |
headers.x-github-event | A request header, in lower case |
query.source | A query string parameter on the webhook URL |
request.timestamp, request.id, request.ip | When it arrived, its ID here, and where it came from |
raw | The body as text, exactly as received |
The filters you will use most
Filters go after a pipe and run left to right.
| Filter | Use it for |
|---|---|
default: "n/a" | Fields that are sometimes absent |
trim, lower, upper | Cleaning up emails, codes and labels |
truncate: 300 | Free text going into a chat message or a field with a length limit |
number, string | A destination that insists on one type when the sender uses the other |
iso | Turning a Unix timestamp into an ISO 8601 date |
length, first, last, join: ", " | Summarising an array |
json, pretty | Dropping a whole object into a message so a person can read it |
urlencode, escape, base64 | Form bodies, XML and encoded values |
The full list is in the template reference.
Not only JSON
The content type of the outgoing request is yours to set, and the body follows it. An older API that expects a form post:
email={{body.user.email | urlencode}}&plan={{body.plan | urlencode}}&source=webhookHeader values are templates too, which is how you pass an idempotency key or the original event ID along:
Idempotency-Key: {{request.id}}
X-Source-Event: {{body.alert.id}}What templates deliberately cannot do
Templates are not a programming language. That is what makes them predictable, and it means a few things need a different approach.
| You want to | Do this instead |
|---|---|
| Loop over an array and reformat each item | Pass the array through whole, or summarise it with length, first and join |
| Do arithmetic, such as cents to dollars | Send the raw number and say what the unit is |
| Send different bodies depending on a field | Use two automations with opposite conditions |
| Look something up in another system | Send the ID and let the destination do the lookup |
If the list on the left describes your whole problem, you want a small service of your own, and that is a fine answer. This post is about where that line sits.
How to write one quickly
- Capture a real request first. Create a URL, register it with the sender and trigger one event. Guessing field names from documentation is where the time goes.
- Select that request and open Automations. Start from Custom request.
- Write the template and watch What would be sent update as you type.
- Press Send test to deliver that one request to the destination, read the reply, and adjust.
Start from a real payload
Get a URL, send it the webhook you need to reshape, and write the template against what actually arrived.
Questions
Can a template loop over an array?
No. Templates have no loops. You can pass an array through whole with its type intact, take its first or last item, count it with length, or join a simple list into text.
Does the output stay valid JSON if a value contains quotes?
Yes. When the template is JSON, values are inserted into the parsed structure and then serialised, so quotes, newlines and other special characters are escaped correctly.
Can I produce something other than JSON?
Yes. Set the content type to plain text, XML or form-encoded and write the body in that format. The urlencode and escape filters make values safe for form bodies and XML.
Keep reading
Webhook filtering
Filter webhooks by event type, amount, branch, header or path before they reach a channel or an API. How conditions work, ten patterns worth copying, and how to express OR.
ReadThe webhook glue server you keep rewriting
Every team has a tiny service that receives a webhook, reformats it and calls another API. The code is twenty lines; running it is the real cost. When to keep writing it and when not to.
Read