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