Desk Webhook Documentation

Introduction

A webhook is an HTTP callback that pushes event information to a server endpoint. In the case of Zoho Desk, a webhook pushes relevant information to the callback URL whenever an event, such as adding a ticket or updating a contact, occurs in the help desk. You can receive any number of events through a single callback URL.

After receiving event information, the callback URL must send a 200 OK response back. Event receipt is considered failed if the callback URL sends a response other than 200 OK or fails to respond within 10 seconds of receiving event information. Similarly, a 410 Gone response results in automatic removal of the webhook subscription.


Zoho Desk supports both HTTP and HTTPS callback URLs. However, HTTPS callback URLs are strongly recommended because they ensure better security.


Also, keep in mind that not all users can create webhooks; the permission to create webhooks is profile-specific. What this means is that only those users who are assigned a profile with the Webhook permission enabled can create webhooks in your portal. To enable/disable the Webhook permission for a profile, go to Setup ---> Users and Control ---> Permissions ---> Profiles, in the Zoho Desk UI.


The table below lists the number of webhooks offered in each Zoho Desk edition.

Edition Webhooks Offered
Free 0
Standard 0
Professional 5
Enterprise 10

You can configure a maximum of 20 webhooks in your help desk portal. However, the number of webhooks that can be enabled depends on the Zoho Desk edition in use. For instance, if you use the Professional edition, you can configure 20 webhooks, out of which only 5 can be enabled at any given time.

If you upgrade the edition of your help desk portal, you can enable inactive webhooks using the isEnabled key. On the contrary, if you downgrade to the Professional edition, the oldest 5 webhooks are retained and the others are disabled; and if you downgrade to the Free edition, all webhooks are disabled.

Webhook Root Endpoint

https://desk.zoho.com/api/v1/

Webhook APIs

These APIs helps you programmatically create, view, update, or delete webhooks that subscribe to the event information from Zoho Desk.

ATTRIBUTES

Attribute Name
Data Type
Description
ignoreSourceId

string

Optional

Client ID exempted from triggering webhooks. The value of this attribute must always be a UUID. For information on how to use this attribute, refer to the Ignoring Webhook Events section.

url

string

Required

Server endpoint to which event information must be sent

name

string

Optional

Name of the webhook

description

string

Optional

Description of the webhook

id

long

ReadOnly

ID of the webhook

isEnabled

boolean

Optional

Key that returns if the webhook is enabled or not

createdBy

long

ReadOnly

ID of user who created the webhook

createdTime

timestamp

ReadOnly

Time of creating the webhook

modifiedTime

timestamp

ReadOnly

Time of modifying the webhook

type

String

ReadOnly

Indicate the type of the webhook.Available webhook types are: CUSTOMER_WEBHOOK and EXTENSION_WEBHOOK

subscriptions

JSONObject

Required

Events that you want to subscribe to

Example

{ "modifiedTime" : "2018-06-04T16:43:45.304Z", "subscriptions" : { "Account_Add" : null, "Contact_Update" : null, "Account_Update" : null, "Ticket_Update" : { "departmentIds" : [ "1234567890", "1234567891" ] }, "Ticket_Add" : { "departmentIds" : [ "1234567890", "1234567891" ] }, "Ticket_Comment_Add" : { "departmentIds" : [ "1234567891" ] }, "Ticket_Thread_Add" : { "departmentIds" : [ "1234567890" ] }, "Contact_Add" : null }, "createdBy" : "100000002344", "isEnabled" : true, "name" : "Test webhook", "createdTime" : "2018-06-04T16:02:20.737Z", "description" : "This webhook listen to ticket events", "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae", "id" : "1234567800", "type" : "CUSTOMER_WEBHOOK", "url" : "www.demoServer.com/webhookTest" }



List all webhooks

This API lists all webhooks configured in your help desk.

Query Params

Param Name
Data Type
Description
GET /api/v1/webhooks

OAuth Scope

Desk.events.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/webhooks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "data" : [ {
    "modifiedTime" : "2018-06-04T16:43:45.304Z",
    "subscriptions" : {
      "Account_Add" : null,
      "Contact_Update" : null,
      "Account_Update" : null,
      "Ticket_Update" : {
        "departmentIds" : [ "1234567890", "1234567891" ]
      },
      "Ticket_Add" : {
        "departmentIds" : [ "1234567891", "1234567895" ]
      },
      "Ticket_Comment_Add" : {
        "departmentIds" : [ "1234567890" ]
      },
      "Ticket_Thread_Add" : {
        "departmentIds" : [ "1234567890" ]
      },
      "Contact_Add" : null
    },
    "createdBy" : "100000002344",
    "isEnabled" : false,
    "name" : "Test webhook",
    "createdTime" : "2018-06-04T16:02:20.737Z",
    "description" : "This webhook listen to ticket events",
    "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae",
    "id" : "1234567800",
    "type" : "CUSTOMER_WEBHOOK",
    "url" : "www.demoServer.com/webhookTest"
  }, {
    "modifiedTime" : "2018-06-04T16:43:45.304Z",
    "subscriptions" : {
      "Ticket_Update" : {
        "departmentIds" : [ "1234567890", "1234567895" ]
      },
      "Ticket_Add" : {
        "departmentIds" : [ "1234567891", "1234567895" ]
      }
    },
    "createdBy" : "100000002344",
    "isEnabled" : true,
    "name" : "Test webhook",
    "createdTime" : "2018-06-04T16:02:20.737Z",
    "description" : "This webhook handles desk events and trigger actions in google extension ",
    "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a204cf194bf",
    "id" : "1234567801",
    "type" : "EXTENSION_WEBHOOK",
    "url" : "www.demoServer2.com/webhookTest"
  } ]
}

Get webhook

This API fetches a single webhook from your help desk.

Query Params

Param Name
Data Type
Description
GET /api/v1/webhooks/{webhook_id}

OAuth Scope

Desk.events.READ

Request Example

$ curl -X GET https://desk.zoho.com/api/v1/webhook/1234567800
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

{
  "modifiedTime" : "2018-06-04T16:43:45.304Z",
  "subscriptions" : {
    "Account_Add" : null,
    "Contact_Update" : null,
    "Account_Update" : null,
    "Ticket_Update" : {
      "departmentIds" : [ "1234567890", "1234567891" ]
    },
    "Ticket_Add" : {
      "departmentIds" : [ "1234567891", "1234567895" ]
    },
    "Ticket_Comment_Add" : {
      "departmentIds" : [ "1234567891" ]
    },
    "Ticket_Thread_Add" : {
      "departmentIds" : [ "1234567891" ]
    },
    "Contact_Add" : null
  },
  "createdBy" : "100000002344",
  "isEnabled" : true,
  "name" : "Test webhook",
  "createdTime" : "2018-06-04T16:02:20.737Z",
  "description" : "This webhook listen to ticket events",
  "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae",
  "id" : "1234567800",
  "type" : "CUSTOMER_WEBHOOK",
  "url" : "www.demoServer.com/webhookTest"
}

Create webhook

This API creates a webhook in your help desk. When this API is invoked, a validation GET Request is sent to the subscription URL. That subscription end-point must respond with a 200 OK message to confirm the subscription. Failure to send a 200 OK message will results in the failure of webhook creation.

POST /api/v1/webhooks

OAuth Scope

Desk.events.CREATE

Request Example

$ curl -X POST https://desk.zoho.com/api/v1/webhooks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{ "subscriptions" : { "Account_Add" : null, "Contact_Update" : null, "Account_Update" : null, "Ticket_Update" : { "departmentIds" : [ "1234567890", "1234567895" ] }, "Ticket_Add" : { "departmentIds" : [ "1234567891", "1234567895" ] }, "Ticket_Comment_Add" : { "departmentIds" : [ "1234567890" ] }, "Ticket_Thread_Add" : { "departmentIds" : [ "1234567891" ] }, "Contact_Add" : null }, "name" : "Test webhook", "description" : "This webhook listen to ticket events", "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae", "url" : "www.demoServer.com/webhookTest" }'

Response Example

{
  "modifiedTime" : "2018-06-04T16:43:45.304Z",
  "subscriptions" : {
    "Account_Add" : null,
    "Contact_Update" : null,
    "Account_Update" : null,
    "Ticket_Update" : {
      "departmentIds" : [ "1234567890", "1234567895" ]
    },
    "Ticket_Add" : {
      "departmentIds" : [ "1234567891", "1234567895" ]
    },
    "Ticket_Comment_Add" : {
      "departmentIds" : [ "1234567891" ]
    },
    "Ticket_Thread_Add" : {
      "departmentIds" : [ "1234567891" ]
    },
    "Contact_Add" : null
  },
  "createdBy" : "100000002344",
  "isEnabled" : true,
  "name" : "Test webhook",
  "description" : "This webhook listen to ticket events",
  "createdTime" : "2018-06-04T16:02:20.737Z",
  "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae",
  "id" : "1234567800",
  "type" : "CUSTOMER_WEBHOOK",
  "url" : "www.demoServer.com/webhookTest"
}

Update webhook

This API updates the details of an existing webhook. If the URL is altered, a validation GET request is sent to the new URL.

PATCH /api/v1/webhooks/{webhooks_id}

OAuth Scope

Desk.events.UPDATE

Request Example

$ curl -X PATCH https://desk.zoho.com/api/v1/webhooks/1234567800
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{ "subscriptions" : { "Account_Add" : null, "Contact_Update" : null, "Account_Update" : null, "Contact_Add" : null } }'

Response Example

{
  "modifiedTime" : "2018-06-04T16:43:45.304Z",
  "subscriptions" : {
    "Account_Add" : null,
    "Contact_Update" : null,
    "Account_Update" : null,
    "Contact_Add" : null
  },
  "createdBy" : "100000002344",
  "isEnabled" : false,
  "name" : "Test webhook",
  "createdTime" : "2018-06-04T16:02:20.737Z",
  "description" : "This webhook listen to ticket events",
  "id" : "1234567800",
  "ignoreSourceId" : "49ad222a-f812-11e7-8c3f-9a214cf093ae",
  "type" : "CUSTOMER_WEBHOOK",
  "url" : "www.demoServer.com/webhookTest"
}

Delete webhook

This API deletes an existing webhook. After this API is executed, the URL in the webhook stops receiving event information.

DELETE /api/v1/webhooks/{webhooks_id}

OAuth Scope

Desk.events.DELETE

Request Example

$ curl -X DELETE https://desk.zoho.com/api/v1/webhooks/1234567800
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

Response Example

200

Events Supported

Zoho Desk webhooks support different events across all help desk modules. Order of events within each module is preserved if there are no failed events, whereas order of events across modules is not preserved.

Attribute Name
Data Type
Description
payload

JSONObject

Current state of the resource

prevState

JSONObject

Previous state of the resource. This key, which is supported only for update events, is made available only if you enabled it while subscribing to the respective event.

eventType

String

Type of the event

eventTime

timestamp

Time when the event occurred


The different events currently supported are as follows:

Ticket Add Event

This event is triggered when a ticket is added. 

Event Type : Ticket_Add

Sample Payload

[ {
  "payload" : {
    "modifiedTime" : "2018-01-23T01:01:04.000Z",
    "ticketNumber" : "397",
    "subCategory" : "Sub General",
    "statusType" : "Open",
    "customFields" : {
      "severityPercentage" : "0.0",
      "dateofPurchase" : "2017-01-23T01:01:04.000Z",
      "url" : "www.demourl.com"
    },
    "subject" : "test ticket",
    "departmentId" : "1234567890",
    "dueDate" : "2018-01-23T04:01:04.000Z",
    "channel" : "Phone",
    "description" : "sample description",
    "resolution" : "sample resolution",
    "closedTime" : null,
    "isTrashed" : false,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "id" : "123456789022",
      "type" : "paid",
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "123456789038"
      }
    },
    "createdTime" : "2018-01-23T01:01:04.000Z",
    "modifiedBy" : "123456789011",
    "id" : "123456789044",
    "email" : "demo.account@zylker.com",
    "customerResponseTime" : "2018-05-09T13:53:42.000Z",
    "firstThread" : null,
    "cf" : {
      "cf_url" : "www.demourl.com",
      "cf_severityPercentage" : "0.0",
      "cf_dateofPurchase" : "2017-01-23T01:01:04.000Z"
    },
    "productId" : "1234987",
    "contactId" : "123456789022",
    "classification" : "Query",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "phone" : "9876543210",
    "webUrl" : "https://desk.zoho.com/support/demoportal/ShowHomePage.do#Cases/dv/a0a83aaa5dc9310455fb22540691f21667d9c06fa8aae2",
    "assignee" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=6044406",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "category" : "General",
    "descAttachments" : [ {
      "size" : "35047",
      "name" : "test image4.png",
      "href" : "https://desk.zoho.com/api/v1/tickets/123456789044/attachments/123456789033/content",
      "id" : "123456789033"
    }, {
      "size" : "53447",
      "name" : "test image.png",
      "href" : "https://desk.zoho.com/api/v1/tickets/123456789044/attachments/123456789034/content",
      "id" : "123456789034"
    } ],
    "status" : "open"
  },
  "eventTime" : "1516669264804",
  "eventType" : "Ticket_Add",
  "orgId" : "3981311"
} ]

Ticket Update Event

This event is triggered when an existing ticket is updated.

Event Type : Ticket_Update

Sample Payload

[ {
  "prevState" : {
    "modifiedTime" : "2018-01-23T01:01:04.000Z",
    "ticketNumber" : "397",
    "subCategory" : "Sub General",
    "statusType" : "Open",
    "customFields" : {
      "severityPercentage" : "0.0",
      "dateofPurchase" : "2017-01-23T01:01:04.000Z",
      "url" : "www.demourl.com"
    },
    "subject" : "test ticket",
    "departmentId" : "1234567890",
    "dueDate" : "2018-01-23T04:01:04.000Z",
    "channel" : "Phone",
    "description" : "Sample description",
    "resolution" : "sample resolution",
    "closedTime" : null,
    "isTrashed" : false,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "id" : "123456789022",
      "type" : "paid",
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "123456789038"
      }
    },
    "createdTime" : "2018-01-23T01:01:04.000Z",
    "modifiedBy" : "123456789011",
    "id" : "123456789044",
    "email" : "demo.account@zylker.com",
    "customerResponseTime" : "2018-05-09T13:53:42.000Z",
    "firstThread" : null,
    "cf" : {
      "cf_url" : "www.demourl.com",
      "cf_severityPercentage" : "0.0",
      "cf_dateofPurchase" : "2017-01-23T01:01:04.000Z"
    },
    "productId" : "1287654",
    "contactId" : "123456789022",
    "classification" : "Query",
    "priority" : "High",
    "assigneeId" : "123456789011",
    "phone" : "12453674904",
    "webUrl" : "https://desk.zoho.com/support/demoportal/ShowHomePage.do#Cases/dv/a0a83aaa5dc935674f68cfb22540691f21667d9c06fa8aae2",
    "category" : "General",
    "status" : "open"
  },
  "payload" : {
    "modifiedTime" : "2018-01-23T01:01:04.000Z",
    "ticketNumber" : "397",
    "subCategory" : "Sub General",
    "statusType" : "Open",
    "customFields" : {
      "severityPercentage" : "0.0",
      "dateofPurchase" : "2017-01-23T01:01:04.000Z",
      "url" : "www.demourl.com"
    },
    "subject" : "test ticket",
    "departmentId" : "1234567890",
    "dueDate" : "2018-01-23T04:01:04.000Z",
    "channel" : "Phone",
    "description" : null,
    "resolution" : "sample resolution",
    "closedTime" : null,
    "isTrashed" : false,
    "contact" : {
      "lastName" : "Carol",
      "firstName" : "Lucas",
      "phone" : "1 888 900 9646",
      "id" : "123456789022",
      "type" : "paid",
      "email" : "carol@zylker.com",
      "account" : {
        "website" : "www.desk.com",
        "accountName" : "desk Account",
        "id" : "123456789038"
      }
    },
    "createdTime" : "2018-01-23T01:01:04.000Z",
    "modifiedBy" : "123456789011",
    "id" : "123456789044",
    "email" : "demo.account@zylker.com",
    "customerResponseTime" : "2018-05-09T13:53:42.000Z",
    "firstThread" : {
      "summary" : "A sample thread",
      "channel" : "FORUMS",
      "createdTime" : "2017-04-13T04:48:12.152Z",
      "id" : "123456789055",
      "content" : "A sample thread full content",
      "ticketId" : "123456789044",
      "direction" : "in"
    },
    "cf" : {
      "cf_url" : "www.demourl.com",
      "cf_severityPercentage" : "0.0",
      "cf_dateofPurchase" : "2017-01-23T01:01:04.000Z"
    },
    "productId" : "1287654",
    "contactId" : "123456789022",
    "classification" : "Query",
    "priority" : "High",
    "assigneeId" : "1892000000056007",
    "phone" : "12453674904",
    "webUrl" : "https://desk.zoho.com/support/demoportal/ShowHomePage.do#Cases/dv/a0a83aaa5dc935674f68cfb22540691f21667d9c06fa8aae2",
    "assignee" : {
      "firstName" : "Lucas",
      "lastName" : "Carol",
      "photoURL" : "https://desk.zoho.com/api/v1/agents/1892000000056007/photo?orgId=6044406",
      "id" : "1892000000056007",
      "email" : "carol@zylker.com"
    },
    "category" : "General",
    "status" : "open"
  },
  "eventTime" : "1516669264804",
  "eventType" : "Ticket_Update",
  "orgId" : "3981311"
} ]

Ticket Delete Event

This event is triggered when an existing ticket is deleted.

Event Type : Ticket_Delete

Sample Payload

[ {
  "payload" : {
    "id" : "123456789044"
  },
  "eventTime" : "1516669264804",
  "eventType" : "Ticket_Delete",
  "orgId" : "3981311"
} ]

Ticket Thread Add Event

This event is triggered when a thread is added to a ticket.

Event Type : Ticket_Thread_Add

Sample Payload

[ {
  "payload" : {
    "summary" : "A sample thread",
    "channel" : "FORUMS",
    "createdTime" : "2017-04-13T04:48:12.152Z",
    "id" : "123456789055",
    "content" : "A sample thread full content",
    "ticketId" : "123456789044",
    "direction" : "in"
  },
  "eventTime" : "1492058892558",
  "eventType" : "Ticket_Thread_Add",
  "orgId" : "3981311"
} ]

Ticket Comment Add Event

This event is triggered when a comment is added to a ticket.

Event Type : Ticket_Comment_Add

Sample Payload

[ {
  "payload" : {
    "modifiedTime" : "2017-09-16T13:50:00.000Z",
    "attachments" : [ {
      "size" : "24355",
      "name" : "TESTIMAGE4.png",
      "id" : "123456789035",
      "href" : "https://desk.zoho.com/api/v1/tickets/123456789044/comments/123456789066/attachments/123456789035/content"
    } ],
    "commentedTime" : "2017-08-16T13:43:50.000Z",
    "isPublic" : false,
    "id" : "123456789066",
    "content" : "test comment",
    "commenterId" : "123456789011",
    "ticketId" : "123456789044"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Ticket_Comment_Add",
  "orgId" : "3981311"
} ]

Ticket Comment Update Event

This event is triggered when a ticket comment is updated.

Event Type : Ticket_Comment_Update

Sample Payload

[ {
  "payload" : {
    "modifiedTime" : "2017-09-16T13:50:00.000Z",
    "attachments" : [ {
      "size" : "24355",
      "name" : "TESTIMAGE4.png",
      "id" : "123456789036",
      "href" : "https://desk.zoho.com/api/v1/tickets/123456789044/comments/123456789066/attachments/123456789036/content"
    } ],
    "commentedTime" : "2017-08-16T13:43:50.000Z",
    "isPublic" : false,
    "id" : "123456789066",
    "content" : "test comment",
    "commenterId" : "123456789011",
    "ticketId" : "123456789044"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Ticket_Comment_Update",
  "orgId" : "3981311"
} ]

Contact Add Event

This event is triggered when a contact is added.

Event Type : Contact_Add

Sample Payload

[ {
  "payload" : {
    "zip" : "600307",
    "lastName" : "demo",
    "country" : "India",
    "secondaryEmail" : "username@zylker.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Approved",
      "cf_singleline1" : "some data about the contact"
    },
    "city" : "Chennai",
    "facebook" : null,
    "mobile" : "9834657812",
    "description" : "Description about the added Contact",
    "type" : "Paid user",
    "title" : "Mechanic",
    "ownerId" : "123456789089",
    "firstName" : "contact",
    "accountId" : "123456789077",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/123456789897/photo",
    "twitter" : null,
    "isTrashed" : false,
    "phone" : "0987654321",
    "street" : "Greens Land",
    "webUrl" : "desk.zoho.com/support/demoportal/ShowHomePage.do#Contacts/dv/a0a83aaa5dc935674f68cfb22540691f21667rt753erty756ij",
    "id" : "123456789022",
    "state" : "Tamil Nadu",
    "email" : "demo.account@zylker.com"
  },
  "eventTime" : "1500278817335",
  "eventType" : "Contact_Add",
  "orgId" : "3981311"
} ]

Contact Update Event

This event is triggered when an existing contact is updated.

Event Type : Contact_Update

Sample Payload

[ {
  "prevState" : {
    "zip" : "641007",
    "lastName" : "demo",
    "country" : "India",
    "secondaryEmail" : "name.here@zylker.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Pending",
      "cf_singleline1" : "old data about contact"
    },
    "city" : "CBE",
    "facebook" : "contact demo",
    "mobile" : "9876543211",
    "description" : "Description about the updated Contact",
    "type" : "Paid user",
    "title" : "Mechanic",
    "ownerId" : "123456789089",
    "firstName" : "contact",
    "accountId" : "123456789077",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/123456789897/photo",
    "twitter" : "contact demo",
    "isTrashed" : false,
    "phone" : "0987654321",
    "street" : "Green Garden",
    "webUrl" : "desk.zoho.com/support/demoportal/ShowHomePage.do#Contacts/dv/a0a83aaa5dc935674f68cfb22540691f21667rt753erty756ij",
    "id" : "123456789022",
    "state" : "Tamil Nadu",
    "email" : "demo.account@zylker.com"
  },
  "payload" : {
    "zip" : "641018",
    "lastName" : "demo",
    "country" : "India",
    "secondaryEmail" : "username@zylker.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Approved",
      "cf_singleline1" : "some data about the contact"
    },
    "city" : "CBE",
    "facebook" : "contact demo",
    "mobile" : "9876543211",
    "description" : "Description about the updated Contact",
    "type" : "Paid user",
    "title" : "Mechanic",
    "ownerId" : "123456789089",
    "firstName" : "contact",
    "accountId" : "123456789077",
    "photoURL" : "https://desk.zoho.com/api/v1/contacts/123456789897/photo",
    "twitter" : "contact demo",
    "isTrashed" : false,
    "phone" : "0987654321",
    "street" : "Rastra prathi",
    "webUrl" : "desk.zoho.com/support/demoportal/ShowHomePage.do#Contacts/dv/a0a83aaa5dc935674f68cfb22540691f21667rt753erty756ij",
    "id" : "123456789022",
    "state" : "Tamil Nadu",
    "email" : "demo.account@zylker.com"
  },
  "eventTime" : "1500278817335",
  "eventType" : "Contact_Update",
  "orgId" : "3981311"
} ]

Contact Delete Event

This event is triggered when an existing contact is deleted.

Event Type : Contact_Delete

Sample Payload

[ {
  "payload" : {
    "id" : "123456789022"
  },
  "eventTime" : "1500278817335",
  "eventType" : "Contact_Delete",
  "orgId" : "3981311"
} ]

Account Add Event

This event is triggered when an account is added.

Event Type : Account_Add

Sample Payload

[ {
  "payload" : {
    "website" : "www.demo.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Pending",
      "cf_singleline1" : "data about account"
    },
    "isTrashed" : false,
    "accountName" : "Demo",
    "phone" : "0987654321",
    "id" : "123456789077",
    "fax" : "12 3456",
    "email" : "demo.account@zylker.com"
  },
  "eventTime" : "1500279084438",
  "eventType" : "Account_Add",
  "orgId" : "3981311"
} ]

Account Update Event

This event is triggered when an existing account is updated.

Event Type : Account_Update

Sample Payload

[ {
  "prevState" : {
    "website" : "www.demo.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Pending",
      "cf_singleline1" : "old data about account"
    },
    "isTrashed" : true,
    "accountName" : "Demo",
    "phone" : "0987654321",
    "id" : "123456789077",
    "fax" : "12 3456",
    "email" : "demo.account@zylker.com"
  },
  "payload" : {
    "website" : "www.demo.com",
    "cf" : {
      "cf_decimal1" : "8907.89",
      "cf_email1" : "anotherusername@zylker.com",
      "cf_picklist1" : "Request Pending",
      "cf_singleline1" : "new data about account"
    },
    "isTrashed" : true,
    "accountName" : "Demo",
    "phone" : "0987654321",
    "id" : "123456789077",
    "fax" : "12 3456",
    "email" : "demo.account@zylker.com"
  },
  "eventTime" : "1500279084438",
  "eventType" : "Account_Update",
  "orgId" : "3981311"
} ]

Account Delete Event

This event is triggered when an existing account is deleted.

Event Type : Account_Delete

Sample Payload

[ {
  "payload" : {
    "id" : "123456789077"
  },
  "eventTime" : "1500279084438",
  "eventType" : "Account_Delete",
  "orgId" : "3981311"
} ]

Department Add Event

This event is triggered when a department is added.

Event Type : Department_Add

Sample Payload

[ {
  "payload" : {
    "isDefault" : false,
    "hasLogo" : false,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "creatorId" : "123456789011",
    "name" : "Sales",
    "description" : "The division of a business that is responsible for selling products or services.",
    "id" : "1234567890",
    "nameInCustomerPortal" : "Sales"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Department_Add",
  "orgId" : "3981311"
} ]

Department Update Event

This event is triggered when an existing department is updated.

Event Type : Department_Update

Sample Payload

[ {
  "prevState" : {
    "isDefault" : false,
    "hasLogo" : false,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "creatorId" : "123456789011",
    "name" : "Sales",
    "description" : "The division of a business that is responsible for selling products or services.",
    "id" : "1234567890",
    "nameInCustomerPortal" : "Sales"
  },
  "payload" : {
    "isDefault" : false,
    "hasLogo" : false,
    "isVisibleInCustomerPortal" : true,
    "isEnabled" : true,
    "creatorId" : "123456789011",
    "name" : "Sales",
    "description" : "The division of a business that is responsible for selling products or services.",
    "id" : "1234567890",
    "nameInCustomerPortal" : "Sales"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Department_Update",
  "orgId" : "3981311"
} ]

Agent Add Event

This event is triggered when an agent is added.

Event Type : Agent_Add

Sample Payload

[ {
  "payload" : {
    "lastName" : "agent",
    "extn" : "876712",
    "roleId" : "123456789088",
    "langCode" : "en_US",
    "mobile" : "7893343211",
    "emailId" : "demo.account@zylker.com",
    "associatedChatDepartmentIds" : [ "14007000000006907" ],
    "associatedDepartmentIds" : [ "14007000000006907", "14007000000002069", "14007000000039717" ],
    "zuid" : "10111",
    "firstName" : "demo",
    "phone" : "43222",
    "profileId" : "123456789099",
    "countryCode" : "en_US",
    "isConfirmed" : false,
    "id" : "123456789011",
    "status" : "ACTIVE"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Agent_Add",
  "orgId" : "3981311"
} ]

Agent Update Event

This event is triggered when an existing agent is updated.

Event Type : Agent_Update

Sample Payload

[ {
  "prevState" : {
    "lastName" : "agent1",
    "extn" : "876712",
    "roleId" : "123456789088",
    "langCode" : "en_US",
    "mobile" : "7893343211",
    "emailId" : "demo.account@zylker.com",
    "associatedChatDepartmentIds" : [ "14007000000006907" ],
    "zuid" : "10111",
    "associatedDepartmentIds" : [ "14007000000006907", "14007000000002069", "14007000000039717" ],
    "firstName" : "demo",
    "phone" : "43222",
    "profileId" : "123456789099",
    "countryCode" : "en_US",
    "isConfirmed" : false,
    "id" : "123456789011",
    "status" : "ACTIVE"
  },
  "payload" : {
    "lastName" : "agent1",
    "extn" : "876712",
    "roleId" : "123456789088",
    "langCode" : "en_US",
    "mobile" : "7893343211",
    "emailId" : "demo.account@zylker.com",
    "associatedChatDepartmentIds" : [ "14007000000006907" ],
    "zuid" : "10111",
    "associatedDepartmentIds" : [ "14007000000006907", "14007000000002069", "14007000000039717" ],
    "firstName" : "demo",
    "phone" : "43222",
    "profileId" : "123456789099",
    "countryCode" : "en_US",
    "isConfirmed" : false,
    "id" : "123456789011",
    "status" : "ACTIVE"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Agent_Update",
  "orgId" : "3981311"
} ]

Agent Delete Event

This event is triggered when an existing agent is deleted.

Event Type : Agent_Delete

Sample Payload

[ {
  "payload" : {
    "id" : "123456789011"
  },
  "eventTime" : "1502891032001",
  "eventType" : "Agent_Delete",
  "orgId" : "3981311"
} ]

Agent Presence Update Event

This event is triggered when an agent comes online or goes offline. However, it happens only when the agent starts a session or ends a session. Concurrent instances of the same session (Zoho Desk in multiple tabs) are not considered.

Event Type : Agent_Presence_Update

Sample Payload

[ {
  "payload" : {
    "emailId" : "demo.account@zylker.com",
    "id" : "68776000000182001",
    "status" : "OFFLINE",
    "zuid" : "10111"
  },
  "eventTime" : "1585732563739",
  "eventType" : "Agent_Presence_Update",
  "orgId" : "3981311"
} ]

Ticket Attachment Add Event

This event is triggered when a sub tab attachment is added to a ticket.

Event Type : Ticket_Attachment_Add

Sample Payload

[ {
  "payload" : {
    "size" : "35047",
    "isTrashed" : false,
    "name" : "testimage.png",
    "creatorId" : "123456789011",
    "createdTime" : "2018-01-23T01:34:55.000Z",
    "isPublic" : false,
    "id" : "123456789036",
    "href" : "https://desk.localzoho.com/api/v1/tickets/123456789044/attachments/123456789036/content",
    "ticketId" : "123456789044"
  },
  "eventTime" : "1516671295177",
  "eventType" : "Ticket_Attachment_Add",
  "orgId" : "3981311"
} ]

Ticket Attachment Update Event

This event is triggered when a sub tab attachment of a ticket is updated.

Event Type : Ticket_Attachment_Update

Sample Payload

[ {
  "payload" : {
    "size" : "35047",
    "isTrashed" : false,
    "name" : "testimage.png",
    "creatorId" : "123456789011",
    "createdTime" : "2018-01-23T01:34:55.000Z",
    "isPublic" : false,
    "id" : "123456789037",
    "href" : "https://desk.localzoho.com/api/v1/tickets/123456789044/attachments/123456789037/content",
    "ticketId" : "123456789044"
  },
  "eventTime" : "1516671295177",
  "eventType" : "Ticket_Attachment_Update",
  "orgId" : "3981311"
} ]

Task Add Event

This event is triggered when a task is added. 

Event Type : Task_Add

Sample Payload

[ {
  "payload" : {
    "modifiedTime" : "2018-08-29T12:48:03.000Z",
    "cf" : {
      "cf_purpose" : "to fix bug"
    },
    "customFields" : {
      "purpose" : "to fix bug"
    },
    "subject" : "Bug Fix #120",
    "completedTime" : null,
    "departmentId" : "4000000012860",
    "dueDate" : null,
    "creatorId" : "4000000015959",
    "description" : "Bug fix",
    "ownerId" : "4000000015959",
    "priority" : "High",
    "createdTime" : "2018-08-29T12:48:03.000Z",
    "id" : "4000000019005",
    "ticketId" : null,
    "status" : "Not Started"
  },
  "eventTime" : "1535546883121",
  "eventType" : "Task_Add",
  "orgId" : "3981311"
} ]

Task Update Event

This event is triggered when an existing task is updated.

Event Type : Task_Update

Sample Payload

[ {
  "prevState" : {
    "modifiedTime" : "2018-08-29T12:48:03.000Z",
    "cf" : {
      "cf_purpose" : "to fix bug"
    },
    "customFields" : {
      "purpose" : "to fix bug"
    },
    "subject" : "Bug Fix #120",
    "completedTime" : null,
    "departmentId" : "4000000012860",
    "dueDate" : null,
    "creatorId" : "4000000015959",
    "description" : "Bug fix ",
    "ownerId" : "4000000015959",
    "priority" : "High",
    "createdTime" : "2018-08-29T12:48:03.000Z",
    "id" : "4000000019005",
    "ticketId" : null,
    "status" : "Not Started"
  },
  "payload" : {
    "modifiedTime" : "2018-08-29T12:48:03.000Z",
    "cf" : {
      "cf_purpose" : "to fix bug"
    },
    "customFields" : {
      "purpose" : "to fix bug"
    },
    "subject" : "Bug Fix #120",
    "completedTime" : null,
    "departmentId" : "4000000012860",
    "dueDate" : null,
    "creatorId" : "4000000015959",
    "description" : "Bug fix ",
    "ownerId" : "4000000015959",
    "priority" : "High",
    "createdTime" : "2018-08-29T12:48:03.000Z",
    "id" : "4000000019005",
    "ticketId" : null,
    "status" : "Not Started"
  },
  "eventTime" : "1535546883121",
  "eventType" : "Task_Update",
  "orgId" : "3981311"
} ]

TimeEntry Add Event

This event is triggered when a time entry is added.

Event Type : TimeEntry_Add

Sample Payload

[ {
  "payload" : {
    "secondsSpent" : "21",
    "parent" : {
      "id" : "4000000373037",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeentryname" : "time1"
    },
    "departmentId" : "4000000012690",
    "minutesSpent" : "23",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description",
    "hoursSpent" : "3",
    "ownerId" : "4000000015891",
    "createdBy" : "4000000015891",
    "createdTime" : "2019-04-22T13:56:45.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000523412",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  },
  "eventTime" : "1535546883121",
  "eventType" : "TimeEntry_Add",
  "orgId" : "3981311"
} ]

TimeEntry Update Event

This event is triggered when an existing time entry is updated.

Event Type : TimeEntry_Update

Sample Payload

[ {
  "prevState" : {
    "secondsSpent" : "21",
    "parent" : {
      "id" : "4000000373037",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time2"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeentryname" : "time2"
    },
    "departmentId" : "4000000012690",
    "minutesSpent" : "23",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description in previous state",
    "hoursSpent" : "3",
    "ownerId" : "4000000015891",
    "createdBy" : "4000000015891",
    "createdTime" : "2019-04-22T13:56:45.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000523412",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  },
  "payload" : {
    "secondsSpent" : "21",
    "parent" : {
      "id" : "4000000373037",
      "type" : "TICKETS"
    },
    "cf" : {
      "cf_timeentryname" : "time1"
    },
    "executedTime" : "2016-06-22T20:30:00.000Z",
    "customFields" : {
      "timeentryname" : "time1"
    },
    "departmentId" : "4000000012690",
    "minutesSpent" : "23",
    "agentCostPerHour" : "3.0",
    "description" : "Time Entry description in payload",
    "hoursSpent" : "3",
    "ownerId" : "4000000015891",
    "createdBy" : "4000000015891",
    "createdTime" : "2019-04-22T13:56:45.000Z",
    "invoiceId" : "4000000008688123",
    "id" : "4000000523412",
    "requestChargeType" : "Customer Service",
    "additionalCost" : "10.0",
    "totalCost" : "20.17"
  },
  "eventTime" : "1535546883121",
  "eventType" : "TimeEntry_Update",
  "orgId" : "3981311"
} ]

TimeEntry Delete Event

This event is triggered when an existing time entry is deleted.

Event Type : TimeEntry_Delete

Sample Payload

[ {
  "payload" : {
    "id" : "123456789044"
  },
  "eventTime" : "1516669264804",
  "eventType" : "TimeEntry_Delete",
  "orgId" : "3981311"
} ]

Ignoring Webhook Events

In some cases, you would not want a webhook to push information if the corresponding event is triggered by an API call you make.

Take for example this scenario, wherein a JIRA workspace and a Zoho Desk help desk are synchronized. If a new comment is created or an existing comment is updated in JIRA, the addition or changes is reflected in Zoho Desk. Similarly, if a comment originally made in JIRA is later updated in Zoho Desk, the change is reflected in JIRA.

Let us say that the JIRA workspace has a webhook that subscribes to the Ticket_Comment_Update event in Zoho Desk.

In such a scenario, if a ticket comment is updated in JIRA, the change is reflected in Zoho Desk via Update Ticket Comment API. Since the comment is now updated in Zoho Desk, the webhook pushes information related to the Ticket_Comment_Update event to JIRA. However, event information does not need to be pushed in this case because the comment was originally updated in JIRA.

So, how can this loop be avoided? By configuring the webhook to not post event information in such a scenario.

This is where the ignoreSourceId attribute comes into play. This attribute makes the avoidance possible by exempting the client ID specified from triggering webhooks. Keep in mind that the value passed for this attribute must be a UUID.

Using the ignoreSourceId Attribute

When making a webhook subscription, you must pass the UUID as the value for the ignoreSourceId attribute. Then, whenever you make an API request, you must include a sourceId header containing the same value passed for the ignoreSourceId attribute in the webhook.

Sample

If the webhook is configured as shown below,

{
"subscriptions": {
"Contact_Update": null,
"Account_Add": null,
"Account_Update": null,
"Ticket_Update": null,
"Ticket_Comment_Update": null,
"Ticket_Add": null,
"Ticket_Comment_Add": null,
"Contact_Add": null
},
"id": "1234567800",
"ignoreSourceId": "49ad222a-f812-11e7-8c3f-9a214cf093ae",
"url":"www.demoServer.com/webhookTest"
}

the API request must be constructed as follows:

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"
  -H "sourceId: 49ad222a-f812-11e7-8c3f-9a214cf093ae"

  -d '{ "isPublic" : "true", "attachmentIds" : ["123456789037"], "content" : "zsu[@user:11550965]zsu Please fix this ASAP" }'