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
      }
    ]
  }
}