Custom JSON template

Custom JSON template

A Custom JSON template is the JSON body you want to send, with {{ … }} placeholders that resolve at delivery time. Strict JSON in the editor; placeholders live inside string literals so the linter stays green.

This is the most flexible template type. Any shape, any nesting, any subset of fields. Works for every event family — not just issue events.


When to use it

  • The receiver expects a specific JSON shape (Slack, Microsoft Teams, GitHub, PagerDuty, custom).

  • You need nesting, arrays, conditionals, or anything beyond a flat object.

  • The webhook fires on non-issue events and you want shape control.

  • You want one template that handles multiple families (use {{entity.…}}).


The smallest template

{ "event": "{{event}}", "issue": "{{issue.key}}", "actor": "{{author}}", "when": "{{timestamp}}" }

For an issue update event, this delivers:

{ "event": "avi:jira:updated:issue", "issue": "ABC-42", "actor": "557058:f2c34d…", "when": "2026-05-04T10:30:45.000Z" }

The two substitution modes

Whole-quote — preserves the original type

When the placeholder is the only content of a JSON string literal ("{{path}}" with optional whitespace), the substitution replaces the whole "..." wrapper with the native JSON of the value.

Template: Output: "key": "{{issue.key}}" "key": "ABC-42" "sp": "{{issue.customfield_10015}}" "sp": 5 ← number, not string "status": "{{issue.status}}" "status": { "name": "...", "id": "..." } ← object "labels": "{{issue.labels}}" "labels": ["bug", "backend"] ← array

This is what you want most of the time. No JSON.parse gymnastics on the receiver.

In-string — composes a string

When the placeholder is part of a larger string literal, the substitution renders a string, escaped for the surrounding literal:

Template: "msg": "Issue {{issue.key}} moved to {{issue.status.name}}" Output: "msg": "Issue ABC-42 moved to In Progress"

Objects and arrays in this position are JSON.stringify-ed and inlined as a string:

Template: "debug": "assignee = {{issue.assignee}}" Output: "debug": "assignee = {\"accountId\":\"...\",\"displayName\":\"John\"}"

If you actually want the stringified form on purpose, use the :json formatter — see Template variables and {{ … }} reference.


Path syntax

Dot-notation. No numeric indices ([0] is not supported).

{{issue.key}} → "ABC-42" {{issue.summary}} → "Fix login bug" (.fields shortcut) {{issue.status.name}} → "In Progress" {{issue.assignee.displayName}} → "John" {{issue.labels}} → ["bug", "backend"] {{issue.fixVersions.last.name}} → "2.5.0" (array accessor) {{issue.customfield_10015}} → 5

The .fields shortcut

Jira's REST shape has top-level properties (key, id, self, changelog) and field properties under .fields (summary, status, priority, …). Webhooks Pro lets you skip the .fields. hop:

  • {{issue.summary}} and {{issue.fields.summary}} return the same thing.

  • The resolver checks the top level first, then .fields.

first, last, length on arrays

{{issue.comment.first}} → first comment {{issue.comment.last.body}} → ADF body of the most recent comment {{issue.comment.length}} → number of comments on this page {{issue.labels.first}} → first label (string) {{issue.fixVersions.last.name}} → most recent fix version's name {{issue.worklog.last.timeSpent}} → time on the most recent worklog

These work on plain arrays and on Jira's pagination wrappers (comment, worklog) — Webhooks Pro peeks into the wrapper's inner array automatically.


Missing values

Placeholder context

If unresolved

Placeholder context

If unresolved

Whole-quote "{{path}}"

becomes null

In-string "prefix {{path}} suffix"

becomes "" (empty string)

So this template:

{ "assignee": "{{issue.nothing}}", "note": "issue={{issue.key}}, missing={{issue.nothing}}" }

…delivers:

{ "assignee": null, "note": "issue=ABC-42, missing=" }

The result is always valid JSON. No undefined, no broken structure.


Examples by event family

Issue update — flat shape for an analytics receiver

{ "key": "{{issue.key}}", "summary": "{{issue.summary}}", "status": "{{issue.status.name}}", "priority": "{{issue.priority.name}}", "assignee": "{{issue.assignee.displayName}}", "labels": "{{issue.labels}}", "updated": "{{issue.updated}}" }

Comment created — link back to the issue

{ "issueKey": "{{issue.key}}", "issueLink": "{{baseUrl}}/browse/{{issue.key}}", "commentBy": "{{comment.author.displayName}}", "commentAt": "{{comment.created}}", "commentId": "{{comment.id}}" }

Project created — non-issue event

{ "event": "{{event}}", "key": "{{project.key}}", "name": "{{project.name}}", "id": "{{project.id}}" }

Family-agnostic — works for many event types

{ "event": "{{event}}", "id": "{{entity.id}}", "name": "{{entity.name}}", "actor": "{{author}}", "when": "{{timestamp}}" }

entity is the alias for whichever family-specific binding is populated (issue, project, version, user, …).

Slack-shaped body

A full example: Send Jira issue updates to Slack.


Formatters

Append :type(pattern) to a placeholder for explicit formatting. Full list and patterns: Template variables and {{ … }} reference.

A few common ones:

{{issue.updated:date(yyyy-MM-dd HH:mm)}} → "2026-05-04 10:30" {{issue.duedate:date(dd/MM/yyyy)}} → "15/05/2026" {{sp:number(0.00)}} for sp=3.1 → "3.10" {{amount:number(#,##0)}} for 12345 → "12,345" {{issue.assignee:json}} → the object as an escaped string

When the render fails

If your Custom JSON template can't be parsed at delivery time (a placeholder produced something that broke the surrounding JSON, an unknown formatter), the consumer:

  1. Falls back to the Default template for that delivery.

  2. Writes a [WARNING] note into the delivery log's error column.

  3. Still sends the delivery — the receiver gets a valid Default body.

This way a typo in your template doesn't take down deliveries silently. Watch the warning column in Webhook Logs after editing a template to catch render failures early.


Common mistakes

Mistake

Symptom

Fix

Mistake

Symptom

Fix

Forget the surrounding quotes for a placeholder you want as a string

Save fails (invalid JSON)

Wrap in "…". The editor's JSON linter catches it.

Use whole-quote for a value that may be missing

Receiver gets null instead of a default

Move to in-string position with a fallback string, or accept null.

Reference an array with [0] syntax

Render fails or returns null

Use first / last / length instead.

Try to use template logic (if / for)

No such thing

Either pre-compute on the receiver, or write multiple webhooks with different JQL.

Hard-code a secret in the template

Token shows up in every delivery log

Use the dedicated header value, not a placeholder.


Related