Desk Invoke API (Proxy)

Desk's invoke API acts as a proxy between the extension and the External Services or Desk for calling the APIs. Desk invoke api is an authenticated API which can be used to make api calls from external services. Desk invoke API can be used to

• Access the Zoho Desk's APIs
• Access the External Service's APIs
• Access the Extension Data Specific APIs such as storage, And configParam APIs

For Using Desk Invoke API Follow the steps given below

1. Add secret key in plugin-manifest.json
   eg: "secret":"my_secret_key_234567"
2. Add Platform Event Callbacks in plugin-manifest.json
       eg:     "callbackListener":{
                      "onZohoAuthorise": "https://zohodeskapp.com/authorized.php",
                      "onConfigParamAdd": "https://zohodeskapp.com/adjustfiler.php",
                      "onUninstall": "https://zohodeskapp.com/revokeWebhook.php"
                  }.
3. Generate HASH for invoke API.

Using Desk Invoke API

The query parameters such as orgId , securityContext and headerparam HASH are required for calling Invoke API . orgId & securityContext will be provided by desk during the Platform event callbacks. HASH should be generated using the SECRET and the Request URL inputs. Refer Generating Hash for Invoke API.

INVOKE API REQUEST FORMAT

INVOKE API RESPONSE FORMAT

INVOKE_API_REQUEST_PAYLOAD

INVOKE_API_RESPONSE_OBJECT 

Description

Sample Response:

 {
  "responseHeaders" : {
    "Cache-Control" : "private,no-cache,no-store,max-age=0,must-revalidate",
    "Set-Cookie" : "drecn=9e1f7200-bcdf-426d-9628-79ff4e9241c8; Path=/; Secure",
    "Vary" : "Accept-Encoding",
    "Expires" : "Thu, 01 Jan 1970 00:00:00 GMT",
    "X-XSS-Protection" : "1",
    "Content-Type" : "application/json;charset=utf-8"
  },
  "response" : "{\"data\":[{\"ticketNumber\":\"176\",\"customerResponseTime\":\"2014-03-22T05:05:08.471Z\",\"productId\":null,\"contactId\":\"1892000000045028\",\"subject\":\"from forum\",\"dueDate\":\"2016-06-01T14:04:07.000Z\",\"departmentId\":\"1892000000006907\",\"channel\":\"Forums\",\"threadCount\":\"72\",\"priority\":\"High\",\"assigneeId\":\"1892000000056007\",\"closedTime\":null,\"commentCount\":\"0\",\"phone\":null,\"contact\":{\"firstName\":\"\",\"lastName\":\"as\",\"phone\":null,\"id\":\"1892000000045028\",\"type\":null,\"email\":\"manojkumar.s+4444@zohocorp.com\",\"account\":{\"website\":\"qwe.com\",\"accountName\":\"Man_Account\",\"id\":\"1892000000980421\"}},\"createdTime\":\"2014-03-06T09:49:50.000Z\",\"id\":\"1892000000094004\",\"email\":\"example@example.com\",\"status\":\"Open\"}]}",
  "statusCode" : "200"
} 

Generate Hash for Invoke API 

To call invoke API, HASH is mandatory. Hash is used to verify the invoke API call was originally made by the extension developer. HASH is an HMAC sha256 encrypted string with the key as app's secret (manifest.secret) provided in the manifest and the input as invokeAPI's payload.

Desk also will generate the HASH with the shared app's secret with the provided payload in the invoke API and will match the provided HASH in the desk invoke API's header. If the HASH does not match with the desk generated HASH, then the invoke API will not be processed.

The same process of authentication can be used by the extension during the extension callback events to verify the callback was originally sent by the desk. A HASH will be sent in the Header of the callback event, developer can generate HASH using payload and secret and allow requests only if HASH is matched.
 

Sample of Invoke API HASH Generation  

Let  Secret (Given in plugin-manifest.json) => "my_secret_key_238392"

Sample Invoke API Inputs =>
requestURL             = https://api.google.com/test
requestType            = POST
queryParams            = {"ticket":"649276000021131197"}
postBody               = {"author": {"name": "jhone Doe","email": "jhondoe@test.com"}}
headers                = {"orgId":376723}
connectionLinkName     = myConnectionLinkName

let stringToHash =
'requestURL=https://api.google.com/test&requestType=POST&queryParams={"ticket":"649276000021131197"}&postBody={"author": {"name": "jhone Doe","email": "jhondoe@test.com"}}&headers={"orgId":376723}&connectionLinkName=myConnectionLinkName'

then, generated HASH = hmac_sha256 ( stringToHash, "my_secret_key_238392" ); //Using HMAC SHA256

Specifying Placeholders in Invoke API

You can specify configParams, authentication details as placeholders while calling the desk invoke API. The placeholders will be replaced with the original values before sending the request to requestURL.

Supported placeholders

Specifying Authentication Details in Invoke API  

Invoke API applies the authentication details specified while calling the API, find the below table for specifying the authentication details while calling the invoke API.

Platform Event Callbacks   

Marketplace supports callbacks for extension's events. Developer can subscribe to the supported events and when the extension event is triggered, callbacks are invoked.

Supported Platform Event Callback's are

• onInstall
• onZohoAuthorise
• onTPAAuthorise
• onTPARevoke
• onUpdate
• onConfigParamAdd
• onConfigParamDelete
• onUninstall

Subscribing to the Events

Extension manifest's callbackListener property is used for declaring the callbacks for the extension's events. To subscribe to an event, specify the callback URL in the manifest for the callbackListener's respective event.

Event Callback Request

Whenever the extension event occurs, the callback URL is triggered with security parameters which can be used to call the authenticated APIs

Event Call back Response Format

 EVENT_CALLBACK_HEADERS
      {
        "HASH"            : "xxxxxxxxx"
      }

EVENT_CALLBACK_PAYLOAD_FORMAT
    {
        "event"            : "onZohoAuthorise",
        "orgId"            : 387238,
        "securityContext"  : "2398deio3qwnx3c9xwi3nc3njkh9jfico"
    }


Example:
{ hash:19924d47bc7e673baae4c1234524486481035ba1da5ceb15c4e11829493d7c4a0 }

{ "securityContext": "edbsnc82d97ed649f59f226b2a7872123444fbc0bb0fc108c4e545f38e52783fffb099c3154c0648af856d26d0d9d82cd", "event": "onInstall", "orgId": "761336011", "dc": "US" } 

EVENT_CALLBACK_PAYLOAD_FORMAT

Events Supported

The events supported in Platform event Callbacks are listed below:

onInstall  

onInstall will be triggered when the customer installs an extension. The developer can subscribe to the event with the URL and perform his logic.  

Example usage  

Creating a Third party resource once the customer installs the extension.

onZohoAuthorise  

Once the end user installs the extension, he needs to authorize the desk & TPA (say jira). onZohoAuthorise will be triggered when the customer authorize the DESK. The developer can subscribe to the event with the URL and perform his logic.  

Example usecase  

Creating a Zoho Desk webhook once the desk authorization is completed.

onTPAAuthorise  

The event will be triggered once the user authorize the Third party app.  

Example usecase  

Subscribing or creating a webhook in third party service.

onTPARevoke  

The event will be triggered once the user revoke the Third party app authorization.

Example usecase  

Revoking or deleting the added webhooks in the third party services.

onUpdate  

The event will be triggered when the user upgrade the extension.

Example usecase  

Adding or Updating config params.

onConfigParamAdd  

The event will be triggered when the customer adds configuration params in the extension.  

Example usecase  

In jira extension, when customer adds configuration params such as domain, jiraAuthKey , developer shall create a jira webhook against the jira account.

onConfigParamDelete  

The event will be triggered when the customer adds configuration params in the extension.  

Example usecase  

In jira extension, when customer deletes configuration params such as domain, jiraAuthKey , developer shall delete jira webhook in the jira account.

onUninstall  

The event is triggered when customer uninstall the extension.

Example usecase  

Operations to be performed during un-installation such as deleting webhooks