Fields template

Fields template

A Fields template is a flat list: each row maps a Jira field to an output key. The result is a flat JSON object the receiver can deserialise with no parsing logic. Issue events only.

If you want shape control beyond a flat object — nested structure, arrays, conditionals — use a Custom JSON template instead.


When to use it

  • The receiver expects a simple flat JSON object with renamed keys.

  • You want to send only a handful of fields, not the whole Default payload.

  • You want non-engineers to maintain the template — Fields is point-and-click; Custom JSON is hand-written.

  • The webhook fires only on Issue, Comment, Worklog, Attachment, Issue Link events.


How a row works

Column

Means

Column

Means

Field (Jira id)

Picked from a dropdown of Jira's field catalog (/rest/api/3/field). System fields (summary, status, priority, assignee, …) and custom fields (customfield_10015) are listed by id and human label.

Key (output)

The name in the JSON body — the receiver sees this. Pick whatever's idiomatic on the receiver side.

Example mapping:

Field (Jira id)

Key (output)

Receives

Field (Jira id)

Key (output)

Receives

issuekey

issueKey

"ABC-42"

summary

title

"Fix login bug"

status

st

{ "name": "In Progress", "id": "3" }

customfield_10015

sp

5

For an issue ABC-42 in In Progress with 5 Story Points:

{ "issueKey": "ABC-42", "title": "Fix login bug", "st": { "name": "In Progress", "id": "3" }, "sp": 5 }

Rules

  • At least one row required — enforced on save.

  • fieldId and fieldKey must each be unique within the template.

  • Missing field → null in the output (distinguishes "absent" from "empty string").

  • Original Jira types preserved — objects stay objects, arrays stay arrays, numbers stay numbers.

  • System fields like issue.key use Jira's special id issuekey (Jira's own convention).


Picking common fields

Field

Jira id

What you get

Field

Jira id

What you get

Key

issuekey

"ABC-42"

Summary

summary

"Fix login bug"

Description

description

ADF object

Status

status

{ "name": "...", "id": "..." }

Priority

priority

{ "name": "...", "id": "..." }

Assignee

assignee

{ "accountId": "...", "displayName": "..." }

Reporter

reporter

same shape as assignee

Issue type

issuetype

{ "name": "Bug", "id": "..." }

Project

project

{ "key": "ACME", "name": "...", "id": "..." }

Labels

labels

["bug", "backend"]

Components

components

[{...}, {...}]

Fix versions

fixVersions

[{...}, {...}]

Due date

duedate

"2026-05-15" (ISO date)

Created

created

"2026-04-01T10:30:00.000+0000"

Updated

updated

same shape as created

Custom fields

customfield_<id>

Whatever Jira returns for that field

If you don't know a custom field's id, open the Jira admin's Custom fields page or run a test webhook with the Default template and inspect the body in Webhook Logs.


What about non-issue events

Fields templates are issue-only. If you attach a Fields template to a webhook that fires on:

  • Project events (project / version / component lifecycle)

  • User events

  • Configuration events (filter / issue-type / custom field / workflow)

…the consumer silently falls back to the Default template for those deliveries and writes a [WARNING] note into the delivery log. The webhook still works; the body shape is just the Default for that family.

If you need a flat-shape body for non-issue events, use a Custom JSON template with the family-specific bindings or the family-agnostic {{entity.…}} alias.


Common patterns

Minimal "issue summary" body

Field

Key

Field

Key

issuekey

key

summary

title

status

status

{ "key": "ABC-42", "title": "Fix login bug", "status": { "name": "In Progress", "id": "3" } }

"Where to find it" body for an external dashboard

Field

Key

Field

Key

issuekey

key

summary

title

assignee

assignee

priority

priority

project

project

Custom-field-heavy body for an analytics receiver

Pick the custom fields you care about; the values keep their original shape, including option lists, multi-selects, and cascading selects.


Common mistakes

Mistake

Effect

Fix

Mistake

Effect

Fix

Attach Fields template to a webhook with project events ticked

Project events fall back to Default; warning in log

Either untick the non-issue events, or switch to Custom JSON.

Two rows with the same output key

Save is rejected

Make output keys unique.

Pick a field and expect a string, but receiver gets an object

Jira returns objects for status, priority, assignee, etc.

Use Custom JSON if you need just status.name, etc.

Pick a field that no longer exists

Output shows null

Audit Fields templates after schema changes.


Related