Introduction

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
Legacy custom object event	custom_object_event	Legacy 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	support	Event tag name. See Custom object events
Legacy custom object event	sunshine	Event tag name. See Legacy custom object events
Activity event	sunshine	Event tag name. See Activity events