This reference information describes supported Zendesk events used to trigger a ZIS Flow when building an integration with Zendesk Integration Services (ZIS).

Both native Zendesk event types and custom events received through inbound webhooks can be referenced in a JobSpec object. Job specs are then installed onto the Zendesk account where the integration will run. This tells ZIS to listen for the specific event type on the account.

When the right type of event is received, ZIS executes the associated flow and passes a JSON object into the first step of the flow. This JSON object includes data about the event's specific changes in the input property. You can access this property in the ZIS flow using the $.input reference path.

The JSON object also includes the account_id, subdomain, and integration_key properties. You can access these properties in the ZIS flow using the respective $.account_id, $.subdomain, and $.integration_key reference paths.

Example:

{  "account_id": 12345,  "integration_key": "my_integration_key",  "subdomain": "my_zendesk_subdomain",  "input": {    "ticket_event": {      "meta": {        "sequence": {          "id": "C20565CD20591B5E81E2206E91ADFB2A",          "position": 1,          "total": 9        },        "version": "1.0",        "occurred_at": "2021-08-12T08:46:37Z",        "ref": "18-646602214"      },      "type": "Ticket Created",      "ticket": {        "assignee_id": 313502247511,        "group_id": null,        "priority": "urgent",        "tags": ["my_tag1"],        "requester_id": 323401287712,        "brand_id": 32040676813,        "id": 1001,        "status": "new",        "via": {          "channel": "web"        },        "organization_id": 361454622831,        "external_id": "41EA202E1-123",        "created_at": "2021-08-12T08:46:37Z",        "type": "problem",        "submitter_id": 323401287712,        "updated_at": "2021-08-12T08:46:37Z",        "form_id": 37201638591      }    }  }}

Top level properties

An event contains the following top-level properties:

Property Data type Description
account_id integer Zendesk account id
integration_key string Integration key retrieved from the ZIS bundle
subdomain string Account subdomain
input object Contains information about the event's changes

Input object

The input object content depends on the event type. It contains a JSON wrapper for the event's data.

Zendesk domain event Property Content
Ticket event ticket_event Ticket Events
User event user_event User Events
Organization event organization_event Organization Events
Custom object event custom_object_event Custom object events
Activity event activity_event Activity events

Each domain has multiple native event types. Each native event type has an associated tag in ZIS to trigger a flow.

In the case of user-defined events received through an inbound webhook receiver, the input object contains the body of the HTTP request.

At-least-once delivery

Zendesk events are designed to fire at least once for a respective action. However, a single action could fire the same event multiple times. This could result in a ZIS flow running multiple times for the same action. For example, a ZIS integration designed to post a Slack message for new tickets may post multiple messages for the same Ticket Created event.

Event sequencing

A single action can trigger a sequence of events. For example, an update to a ticket may trigger both the Comment Created and Status Changed events. All events include an input.{event_domain}.meta.sequence object. This object contains information about the event's sequence. For example, a ticket event contains the object in the input.ticket_event.meta.sequence property.

The input.{event_domain}.meta.sequence object contains the following properties:

Property Data type Description
id string id of the action that triggered the event. Events with the same sequence id were triggered by the same action
position integer Order of the event within the sequence. Zendesk doesn't guarantee this order
total integer Number of events in the sequence

Zendesk doesn't guarantee the order of sequence ids or sequence positions. For example, an event with a sequence id of "22222" may occur before or after an event with a sequence id of "11111". Similarly, an event with a sequence position of "2" may occur before or after an event with a sequence position of "1". A Ticket Created event may not always have a sequence position of "1". Don't use the order of sequence ids or sequence positions as the basis for an integration's business logic.

ZIS doesn't guarantee a first in, first out (FIFO) processing of events. ZIS may process events from multiple sequences out of order.

Referencing an event in a JobSpec

An event is referenced in a job spec to trigger a flow.

Example:

"jobspec": {  "type": "ZIS::JobSpec",  "properties": {    "name": "example_job_spec",    "event_source": "support",    "event_type": "ticket.TicketCreated",    "flow_name": "zis:example_integration:flow:example_flow"  }}

To associate a Zendesk event with a flow, you specify the event_source and the event tag name for event_type.

Zendesk event event_source event_type
Ticket event support Event tag name. See Ticket events
User event support Event tag name. See User events
Organization event support Event tag name. See Organization events
Custom Object event sunshine Event tag name. See Custom Object events
Activity event sunshine Event tag name. See Activity events