Webhook payload templates

When a webhook is configured with a custom payload, the request body is rendered from a Twig template. The template receives variables drawn from the event that triggered the webhook, available in camelCase format.

• Global variables
• Variables by event
• Variable reference
  • case
  • Field values
  • Address
  • Person
  • Organisation
  • attachment
  • field
  • user
  • Event-specific variables
• Working with dates
• Tips
• Examples

Global variables

These two variables are present for all events:

Variable	Type	Description
action	string	The event type identifier: case_created, case_transitioned, attachment_added, field_created, field_updated, rule_action, user_created, or user_updated. For User events on payload version 1, the value is create or update instead.
version	int	The payload version number

Variables by event

The table below shows which top-level objects are available for each event:

Event	case	attachment	field	user	Event-specific
Attachment added	✓ ¹	✓			addedBy
Case created	✓				createdBy
Case transitioned	✓				transition, transitionedBy, previousStatus, newStatus
Field created			✓
Field updated			✓
Rule action	✓				initiatedBy, trigger, context
User created				✓ ²
User updated				✓ ³

¹ On Attachment added events, case only provides reference and type. ² On User created event, user also provides person only if the payload is custom. ³ On User updated event, user also provides person only if the payload is custom.

Variable reference

case

Property	Type	Description
case.reference	string	Case reference
case.createdAt	DateTime	Creation timestamp
case.updatedAt	DateTime	Last updated timestamp
case.status.slug	string	Status slug
case.status.title	string	Status title
case.status.type	string	Status type
case.type.slug	string	Case type slug
case.type.title	string	Case type title
case.type.service.slug	string	Service group slug
case.type.service.title	string	Service group title
case.values	map	Field values keyed by field slug — see Field values
case.addressRelationships	array	Linked addresses — see Address
case.personRelationships	array	Linked people — see Person
case.organisationRelationships	array	Linked organisations — see Organisation

createdAt, updatedAt, status, values, addressRelationships, personRelationships, and organisationRelationships are not available when case appears in an Attachment added event.

Field values

Case field values are accessed as case.values['field-slug']. Each value exposes:

Property	Type	Description
type	string	Field type (e.g. text, choice, date, datetime, checkbox, textarea, url)
name	string	Field slug
redacted	bool	Whether the value has been redacted
value	mixed	The field value. A string for text/date fields, a boolean for checkboxes, and an array of strings for multi-choice fields. null if redacted.

Example:

{% if case.values['priority'] is defined %}
  Priority: {{ case.values['priority'].value }}
{% endif %}

For field names that contain hyphens or start with a number, always use bracket notation. For other field names, dot notation also works:

{{ case.values['123-my-field'].value }}   {# required for hyphenated or numeric-start slugs #}
{{ case.values.my_field.value }}          {# works for simple slugs #}

Address

Used within case.addressRelationships[n].address, person.addresses[n], person.primaryAddress, and organisation.address.

Property	Type
summary	string
street	string
paon	string
saon	string
locality	string
town	string
postTown	string
postCode	string
administrativeArea	string
uprn	string
usrn	string
easting	int
northing	int
externalReference	string
reference	string
type	string
custom	bool

Person

Used within case.personRelationships[n].person and createdBy.person. Also used within user.person on user created and user updated events for custom payload.

Property	Type	Description
reference	string	Person reference
name	string	Full name
email	string	Email address
primaryAddress	Address	Primary address — see Address
addresses	array	All linked addresses — see Address

Organisation

Used within case.organisationRelationships[n].organisation.

Property	Type	Description
reference	string	Organisation reference
name	string	Organisation name
address	Address	See Address

attachment

Available on the Attachment added event.

Property	Type	Description
attachment.fileName	string	File name
attachment.description	string	Description
attachment.identifier	string	Attachment identifier
attachment.mimeType	string	MIME type
attachment.size	int	File size in bytes
attachment.downloadUrl	string	Time-limited download URL
attachment.downloadUrlExpiry	DateTime	When the download URL expires

field

Available on Field created and Field updated events.

Property	Type	Description
field.slug	string	Field slug
field.type	string	Field type (e.g. text, choice, date)
field.title	string	Field label
field.expanded	bool	Whether the field is displayed expanded (choice fields only)
field.multiple	bool	Whether multiple selections are allowed (choice fields only)
field.choices	array	Available choices, each with label, value, and disabled properties (choice fields only)
field.defaultChoices	array	Default selected values (choice fields only)

user

Available on User created and User updated events.

Property	Type	Description
user.id	int	User ID
user.reference	string	User reference
user.email	string	Email address
user.forename	string	First name
user.surname	string	Last name
user.name	string	Full name
user.photo	string	Photo URL
user.timezone	string	Timezone
user.enabled	bool	Whether the account is enabled
user.emailVerified	bool	Whether the email has been verified
user.incomplete	bool	Whether the profile is incomplete
user.group.slug	string	User group slug
user.group.title	string	User group title
user.privilegeLevel.slug	string	Privilege level slug
user.privilegeLevel.title	string	Privilege level title
user.type.slug	string	User type slug
user.type.title	string	User type title
user.createdAt	DateTime	When the account was created
user.updatedAt	DateTime	When the account was last updated

For custom payload, the following is also available in addition to the above:

Property	Type	Description
user.person.reference	string	Person reference
user.person.name	string	Full name
user.person.email	string	Email address
user.person.addresses	array	All linked addresses — see Address
user.person.primaryAddress.summary	string
user.person.primaryAddress.street	string
user.person.primaryAddress.paon	string
user.person.primaryAddress.saon	string
user.person.primaryAddress.locality	string
user.person.primaryAddress.town	string
user.person.primaryAddress.postTown	string
user.person.primaryAddress.postCode	string
user.person.primaryAddress.administrativeArea	string
user.person.primaryAddress.uprn	string
user.person.primaryAddress.usrn	string
user.person.primaryAddress.easting	int
user.person.primaryAddress.northing	int
user.person.primaryAddress.externalReference	string
user.person.primaryAddress.reference	string
user.person.primaryAddress.type	string
user.person.primaryAddress.custom	bool

Event-specific variables

Attachment added

Variable	Type	Description
addedBy.reference	string	User reference
addedBy.name	string	Full name
addedBy.email	string	Email address

Case created

Variable	Type	Description
createdBy.reference	string	User reference
createdBy.name	string	Full name
createdBy.email	string	Email address
createdBy.group.slug	string	User group slug
createdBy.group.title	string	User group title
createdBy.privilegeLevel.slug	string	Privilege level slug
createdBy.privilegeLevel.title	string	Privilege level title
createdBy.type.slug	string	User type slug
createdBy.type.title	string	User type title
createdBy.person	Person	See Person

Case transitioned

Variable	Type	Description
transition.slug	string	Transition slug
transition.title	string	Transition title
transitionedBy.reference	string	User reference (null if triggered by a rule)
transitionedBy.name	string	Full name
transitionedBy.email	string	Email address
previousStatus.slug	string	Status slug before the transition
previousStatus.title	string	Status title before the transition
previousStatus.type	string	Status type before the transition
newStatus.slug	string	Status slug after the transition
newStatus.title	string	Status title after the transition
newStatus.type	string	Status type after the transition

Rule action

Rule action templates have access to case (see above) plus the following:

Variable	Type	Description
initiatedBy	User (partial)	The user who triggered the rule. null for time-based triggers (Date, Date and time, Time in status). Provides: reference, name, email, group, privilegeLevel, type.
trigger.type	string	One of: transition, field_changed, event, date, date_time, time_in_status
context	object	Contextual data for the trigger. Structure depends on trigger.type. null when not applicable.

Trigger context by type:

trigger.type	Available properties
transition	trigger.transition (slug, title); context.previousStatus, context.newStatus (slug, title, type)
field_changed	trigger.field (slug, type, title); context.originalValue, context.updatedValue — see Field values
date	trigger.dateDefinition (slug, title, basedOn, delta); trigger.dateDefinition.field (slug, type, title) — only present when basedOn is case_field. context is null.
date_time	trigger.triggerAt (DateTime). context is null.
time_in_status	trigger.status (slug, title, type); trigger.minutes (int). context is null.
event	trigger.event (string identifier). See table below for context structure.

Event trigger context (when trigger.type is event):

trigger.event	context
case.created	null
case.attachment.new	context.attachment — see attachment
case.message.new	context.message: headerId, subject, content, createdAt, recipients
case.message.reply	Same structure as case.message.new
case.note.new	context.note.createdAt
case.membership.added	context.membership.type (user or user_group); context.membership.user or context.membership.userGroup
case.membership.removed	Same structure as case.membership.added

Working with dates

Date properties are DateTime objects. Use the |date() filter to format them. Any PHP date format string is valid:

{{ case.createdAt|date('c') }}           {# ISO 8601: 2019-10-09T13:10:10+00:00 #}
{{ case.createdAt|date('d/m/Y H:i') }}   {# 09/10/2019 13:10 #}

Tips

• Use {% if variable is defined %} to guard against missing data, particularly for initiatedBy, transitionedBy, and rule action context objects.
• When iterating all case field values:

  {% for slug, fieldValue in case.values %}
    {{ slug }}: {{ fieldValue.value }}
  {% endfor %}

• The |default() filter is useful for variables that may be null: {{ transitionedBy.email|default('system') }}

Examples

Case created

{
  "reference": "{{ case.reference }}",
  "case_type": "{{ case.type.slug }}",
  "created_by": "{{ createdBy.email }}",
  "created_at": "{{ case.createdAt|date('c') }}"
}

Case transitioned

{
  "reference": "{{ case.reference }}",
  "transition": "{{ transition.slug }}",
  "previous_status": "{{ previousStatus.slug }}",
  "new_status": "{{ newStatus.slug }}",
  "transitioned_by": "{{ transitionedBy.email|default('system') }}"
}

User created

{
  "id": {{ user.id }},
  "reference": "{{ user.reference }}",
  "email": "{{ user.email }}",
  "name": "{{ user.name }}",
  "created_at": "{{ user.createdAt|date('c') }}",
  "enabled": {{ user.enabled ? 'true' : 'false' }}
}

Rule action — transition trigger

{
  "case_reference": "{{ case.reference }}",
  "trigger_type": "{{ trigger.type }}",
  "transition": "{{ trigger.transition.slug }}",
  "previous_status": "{{ context.previousStatus.slug }}",
  "new_status": "{{ context.newStatus.slug }}",
  "initiated_by": "{{ initiatedBy.email|default('system') }}"
}

Rule action — field changed trigger

{
  "case_reference": "{{ case.reference }}",
  "field": "{{ trigger.field.slug }}",
  "original_value": "{{ context.originalValue.value|default('null') }}",
  "updated_value": "{{ context.updatedValue.value|default('null') }}"
}