Webhooks

What is Webhook

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. Please refer to this document to learn more about webhooks in Desk.

Webhook in Extension

Marketplace supports webhooks in extensions, allowing a marketplace app to create extension-specific webhooks in Desk. These webhooks are restricted to the extension app alone, so the normal user cannot make any changes to them.

As an extension developer, you must specify the webhook details in the resources.json file of a specific extension. So that the webhook will be created on authorizing the extension and deleted on the event of extension uninstallation. We can apply department-level filtering to webhook events based on the departments that are chosen in the extension configuration.

Note: Extension webhooks are allowed only for org-based extensions

Note: Ignore the departmentIds key while giving the subscriptions details in resources.json file.

Field	Required	Type	Description
resourceName	yes	string	Unique identifier of the created webhook in the resources. Please refer this document for know about resourceName
url	yes	string	Server endpoint to which event information must be sent
name	yes	string	Name of the webhook
description	no	string	Description of the webhook
ignoreSourceId	yes	string	Client ID exempted from triggering webhooks. The value for this attribute must always be UUID. For information on how to use this attribute, refer to the Ignoring Webhook Events section.
subscriptions	yes	JSONObject	Events that you want to subscribe to. Please refer this document to know more about the supported events and its payload.

Note:
For certain scenarios, we do not require notification from the webhook to our third party service. Like when we call the ticket comment add api from our third party service to Desk,a webhook with the ticket comment add event subscribed will be triggered. We don't need this notification, as the comment add operation is originated from the third party service. For this situation, we need to add the UUID mentioned in the "ignoreSourceId" in the "sourceId" header when calling the comment add API.

Note:If you have used "includEventsFrom": [AUTOMATION] in an older version for notifying escalation events, and you need to remove or modify this behavior in a newer version, just removing the key won't be enough. Developers should update the resource.json by setting "includEventsFrom": null in the webhook JSON to disable notifying escalation events.

Sample Webhook Resource

Copied{
  "webhook": {
    "resourceName": "webhook1",
    "url": "https://demowebhook.com/callbackurl",
    "name": "Demo extension webhook",
    "description": "Demo extension webhook listen to ticket events",
    "subscriptions": {
      "Ticket_Add": null,
      "Ticket_Thread_Add": null,
      "Ticket_Comment_Add": null,
      "Ticket_Comment_Update": null,
      "Ticket_Update": {
        "fields": [
          "status"
        ]
      }
    },
    "includeEventsFrom": ["AUTOMATION"],
    "ignoreSourceId": "2df92c1a-973a-48f5-95b7-5792c68b9c36"
  }
}

Authorisation in Extension Webhook

To use the extension webhook, you should include the extension-specific scope Desk.events.ALL in the authorisation scope list, and the authorisation details should be defined inside the zohoAuthorisation key in the plugin-manifest file.

Responses

If you fail to mention the Desk.events.ALL scope inside the zohoAuthorisation key, the The response '422 - Unprocessable entity error response' will be received .

Response:

Copied


{
    "message": "{\"errors\":{\"resourcesJson\":[\"The webhook resource should have connection in zohoAuthorisation with Desk.events.ALL scope.\",\"webhook should be configured for org exension type\"]}}"
}

Sample Plugin-manifest entry with Zoho Authorisation - using Connections

Copied{
	"connectionLinkName": "ext_webhook",
	"connectionName": "ext_webhook",
	"serviceName": "zlabs_integration",
	"userAccess": true,
	"isUserDefinedService": false,
	"sharedBy": "761336011",
	"scope": [
		"Desk.events.ALL"
	]
}