Event callbacks

You can provide an endpoint that lets Zendesk Support send callbacks to your service. The callbacks map to specific actions that occur in the Channel Framework. For a complete list see Callback types.

To enable this feature you must build a callback endpoint and specify it in the Integration Manifest.

Example

"urls": {
  "event_callback_url": "https://omniwear.com/integrations/instagram/event_callback",
  ...
}

Your endpoint may behave in any manner you see fit. Example use cases are:

• Forwarding the requests to a logging service.
• Manually inspecting the responses to assist in debugging.
• Using the provided information to make follow-up actions with Zendesk Support.

JSON Schemas

Each event callback conforms to a JSON Schema file. The schemas are available at https://github.com/zendesk/any_channel_json_schemas.

Request format

Zendesk Support makes a POST request with the following JSON object to the event_callback_url provided in your integration manifest. Callback events are aggregated before they are sent so Zendesk Support will often send multiple events per request. Every event will have a common set of attributes. The data attribute will contain a different type of JSON object depending on the event type_id.

Name	Type	Comments
events	array	An array of JSON objects each of which represents a specific callback event

Callback event format

Name	Type	Comments
type_id	string	Machine readable string describing the callback event
timestamp	datetime	Time of callback request in RFC 3339 date-time format. Example: '2015-09-08T22:48:09Z'
subdomain	string	Subdomain of the Zendesk Support account the event is for
integration_name	string	Name of the integration
integration_id	string	Id of the integration
error	string	Optional description of any errors that occurred
data	object	Contains event specific information

Example

{
  "events": [
    {
      "type_id":          "pull_request",
      "timestamp":        "2015-09-08T22:48:09Z",
      "subdomain":        "support",
      "integration_name": "Life bar",
      "integration_id":   "25e2b1b2-e7f9-4485-8331-9f890aa9e2b8",
      "error":            "A payload received in response to a pull request contained invalid JSON. Errors - The property '#/' did not contain a required property of 'name'. This is a recoverable error and the integration account will continue to be polled for new data.",
      "data":             {
        "integration_account_name": "Life bar instagram",
        "url":                      "https://omniwear.com/integrations/instagram/pull",
        "request_id":               "5760dcea-6bd4-4b17-9bf2-f417ebd5cbc5"
      }
    }
  ]
}

Response format

Return a 200 response with an empty body to indicate a callback was successfully received and an appropriate http status when any errors occur.

Callback types

create_integration

A create_integration event is sent whenever a customer installs your channel integration. The event has a type_id of create_integration. It populates the data attribute with the following JSON object.

Name	Type	Comments
manifest_url	string	The url of the manifest used to create the integration

Example

{
  "type_id": "create_integration",
  ...
  "data": {
    "manifest_url": "https://omniwear.com/integration_manifest.json"
  }
}

destroy_integration

A destroy_integration event is sent whenever a customer removes your channel integration. The event has a type_id of destroy_integration. It populates the data attribute with the following JSON object.

Name	Type	Comments
manifest_url	string	The url of the manifest used to create the integration

Example

{
  "type_id": "destroy_integration",
  ...
  "data": {
    "manifest_url": "https://omniwear.com/integration_manifest.json"
  }
}

create_integration_instance

A create_integration_instance event is sent whenever a customer creates an integration instance. The event has a type_id of create_integration_instance. It populates the data attribute with the following JSON object.

Name	Type	Comments
metadata	string	The metadata persisted on the integration instance

Example

{
  "type_id": "create_integration_instance",
  ...
  "data": {
    "metadata": "{\"instagram_username\":\"omniwear\",\"instagram_oauth_token\":\"xyzabc\"}"
  }
}

destroy_integration_instance

A destroy_integration_instance event is sent whenever a customer removes an integration instance. The event has a type_id of destroy_integration_instance. It populates the data attribute with the following JSON object.

Name	Type	Comments
metadata	string	The metadata that was persisted on the integration instance

Example

{
  "type_id": "destroy_integration_instance",
  ...
  "data": {
    "metadata": "{\"instagram_username\":\"omniwear\",\"instagram_oauth_token\":\"xyzabc\"}"
  }
}

pull_request

A pull_request event is sent when Zendesk Support performs a pull action to an integration account. If anything goes wrong in the process of making the request and parsing the response, the error attribute of the event JSON object is populated. The event has a type_id of pull_request. It populates the data attribute with the following JSON object.

Name	Type	Comments
integration_account_name	string	The name of the integration account the pull was performed on
url	string	The url which was used to perform the pull request
request_id	string	A unique identifier Zendesk Support assigns to each pull request it performs
duplicate_external_ids	array	An array of objects representing external_ids that Zendesk has already processed

The duplicate_external_ids objects are represented by the following JSON object.

Name	Type	Required	Comments
external_id	string	yes	The external_id that Zendesk has already processed
request_id	string	yes	The unique identifier for the request the external_id was successfully processed in
ticket_id	string	no	Zendesk Support ID of the ticket created as a result of processing the external_id
comment_id	string	no	Zendesk Support ID of the comment created as a result of processing the external_id

Example

{
  "type_id": "pull_request",
  ...
  "data": {
    "integration_account_name": "Life bar instagram",
    "url":                      "https://omniwear.com/integrations/instagram/pull",
    "request_id":               "5760dcea-6bd4-4b17-9bf2-f417ebd5cbc5",
    "duplicate_external_ids": [
      {
        "external_id": "123",
        "request_id": "08779cf7-44db-4929-83aa-4c2b0ca51c17",
        "ticket_id": "456",
        "comment_id": "789"
      },
      {
        "external_id": "abc",
        "request_id": "e0846039-20fe-48e9-b024-915731ac8a22",
        "ticket_id": "def",
        "comment_id": "ghi"
      },
    ]
  }
}

resources_created_from_external_ids

A resources_created_from_external_ids event is periodically sent to provide an overview of what resources were created as a result of an interaction with the Channel Framework. The event has a type_id of resources_created_from_external_ids. It populates the data attribute with following JSON object.

Name	Type	Comments
request_id	string	An identifier for the request that causes the resources to be created
resource_events	array	An array of JSON objects each of which represents an external_id and an associated Zendesk Support resource

The resource_events are represented by the following JSON object.

Name	Type	Required	Comments
type_id	string	yes	Machine readable string representing the type of comment that was created. See below for full list
external_id	string	yes	The external_id Zendesk Support received from your integration
comment_id	string	yes	The id of the comment created
ticket_id	string	yes	The id of the ticket the comment was created on
follow_up_id	string	no	An optional attribute that refers to the id of a ticket that a follow-up ticket was created from

The type_id attribute will have one of the following values:

• comment_on_new_ticket - A new comment was created on a new ticket.
• comment_on_existing_ticket - A new comment was created on an existing ticket.
• comment_on_follow_up_ticket - A new comment was created on a new ticket that was a follow-up to an existing ticket.
• external_id_associated_with_channelback - Zendesk associated an external_id returned from your integration with a channelback comment.

Example

{
  "type_id": "resources_created_from_external_ids",
  ...
  "data": {
    "request_id":      "5760dcea-6bd4-4b17-9bf2-f417ebd5cbc5",
    "resource_events": [
      {
        "type_id":     "comment_on_new_ticket",
        "external_id": "omniwear-123",
        "comment_id":  111,
        "ticket_id":   222
      },
      {
        "type_id":     "comment_on_existing_ticket",
        "external_id": "omniwear-456",
        "comment_id":  333,
        "ticket_id":   444
      },
      {
        "type_id":      "comment_on_follow_up_ticket",
        "external_id":  "omniwear-789",
        "comment_id":   444,
        "ticket_id":    555,
        "follow_up_id": 666
      },
      {
        "type_id":      "external_id_associated_with_channelback",
        "external_id":  "omniwear-789",
        "comment_id":   444,
        "ticket_id":    555
      }
    ]
  }
}