/
Payload templates

Payload templates

A payload template decides what JSON body Webhooks Pro sends. Two user-editable types — Fields (pick fields, get a flat object) and Custom JSON (write your own JSON with {{ … }} placeholders). Plus two built-in system templates (Default, Empty Body) that exist on every install.

When to use which

You want

Pick

You want

Pick

Send the standard Jira payload, no shaping

Default (built-in)

Send only the trigger notification, no body content

Empty Body (built-in)

Pick a handful of issue fields, rename them, send a flat object

Fields

Match a specific receiver's expected JSON shape (Slack, GitHub, custom)

Custom JSON

One template that handles many event families

Custom JSON with {{entity.…}} paths

Fields templates only make sense for Issue-family events. Project / version / user / filter / etc. fall back to Default if attached to a Fields template.

How it works

Payload-templates-How-it-works.png

 

 

A webhook references one template by name. At delivery time, Webhooks Pro:

  1. Loads the chosen template.

  2. If Fields, builds a flat object from the picked fields.

  3. If Custom JSON, substitutes {{ … }} placeholders against the event context.

  4. Sends the rendered body to the webhook URL.

If the render fails (Fields template on a non-issue event, Custom JSON that doesn't parse), the consumer silently falls back to the Default payload and writes a [WARNING] into the delivery log.

Configure

The Payload Templates page lists every template on this site. From the list:

  • Create payload template — opens the editor, pick Fields or Custom JSON.

  • Click any row to edit. System templates (Default, Empty Body) open read-only.

  • Used by card on the right shows how many webhooks currently reference the template.

  • Export button downloads every user-defined template as JSON (system templates excluded).

  • Delete prompts before removing — and automatically detaches the template from any webhooks using it (those switch to Default).

The webhook form's Payload Template dropdown is where you wire a template to a webhook. The link beside the dropdown opens the template editor in a new tab so your webhook edits aren't lost.

Sub-pages

The two built-in (system) templates

Every install has these. They cannot be edited or deleted; they exist so a webhook can always render something.

Template

What it sends

Template

What it sends

Default

The built-in family-specific payload — Issue / Comment / Worklog / Project / etc. depending on the event. The standard "everything you might need" body.

Empty Body

{} — useful when the receiver only needs the trigger notification and will fetch its own data afterward.

Detail on what Default looks like for each event family: The built-in Default template.

Save-time validation

The editor refuses to save when:

  • Fields: no field rows, or any row has an empty field id / key.

  • Fields: duplicate fieldId or duplicate fieldKey within the same template.

  • Custom JSON: empty body, or body that doesn't pass JSON.parse.

  • Either: empty name.

Limits and gotchas

  • Fields templates only work on issue events. Attached to a non-issue event, the consumer falls back to Default and notes a warning.

  • Custom JSON must be valid JSON in the editor (placeholders live inside string literals, so the JSON linter stays green). Anything else is rejected on save.

  • Whole-quote substitution preserves type. "{{issue.labels}}" becomes ["bug","backend"] (an array, not a string). See Template variables and {{ … }} reference.

  • Missing values become null in whole-quote position and "" in in-string position. No "undefined" leaks into the body.

  • Don't put secrets in placeholders. Anything resolved from a Jira field ends up in the delivery log. Static auth tokens belong in literal header values.

  • Deleting a template auto-resets webhooks that referenced it to Default. The Used by card on the editor lets you preview impact.

Related