Webhook based extensions

What are extensions in Cliq ?

Extensions are a great way to connect to a third party service thereby bringing in your everyday tools and work items together in one place- Cliq.

Webhook based extensions

Webhook based extensions are as same as extensions using deluge unlike a HTTP POST request will be triggered to the configured URL when a component bundled in an extension is invoked. Further, the execution details are sent in the body of the request.

Follow the given steps below to have a better understanding of the working:

1. In the extensions page click on the Create Extension button and give your extension a name and a small description. Type in the callback URL of the server that you want to connect Cliq with.

2. Include the platform components (commands, bots, functions and message actions) by clicking on the Add button.

3. Further click on the Create Extension button to create the extension.

What will happen when you perform an action on the Cliq platform?

For any platform component to work, be it executing a slash command or clicking on a button or to send a message to a bot, there needs to be an invocation to happen in the backend. When a component bundled in an extension is invoked, a HTTP POST request will be made. Further the request is processed by the developer based on the data in the request and returns a response as defined in Cliq.

Consents

Executing a platform component in Cliq for the first time will throw a dialog pop-up to the user asking them to grant permission for the command or bot or message action or function to access and authenticate the variables comprising personal information of the user. The request payload will contain developer enabled user consent variables and their execution details.

Attachments handling (expiry time based)

When an attachment is added while executing a slash command, sharing files to bots, submitting files through forms and performing an action on attachment messages, a unique URL is generated and is sent in the request payload. The attachment can further be downloaded by triggering a GET request for once within a time span of one minute after which the URL becomes invalid.

Handling execution responses

Every time that a platform component is triggered using an extension , a response URL is generated and sent in the request payload. To post the same as a response to the user, a POST request has to be made to the response URL generated by including the response message in the body of the request. The developer can respond to the same request within a time span of 5 seconds or can make use of the one time call back URL.

Given below are the list of handlers that support response URL,

1. Command execution handler

2. Message action handler

3. Bot welcome handler

4. Bot message handler

5. Bot context handler

6. Function button handler

7. Function form submit handler

Note: The maximum time span of the response URL is two minutes after which it expires.

Sample syntax for posting the response

A HTTP POST request is made to the response URL in the payload

Sample response URL

https://cliq.zoho.com/v2/extensions/2980/responses/17202823900615741410013820

Sample data to be passed in the body

{"output" : {"text":"Hello"}}

Signature

Signature is a way to validate if the request is made from Cliq. To verify the signature, the request body is signed and sent in the X-Cliq-Signature header of the request. Users can verify the signature using the public key displayed under the connectors tab in the extension page.

Note: The first key appearing in the extension page is the active public key with which you can verify the signature.

Sample active public key

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA14O1bOavDLetgBr4p4VI91yg5YdDjxxXGZbpoBFtg5OTlY0JtBpzHaAyISPfE0b6ckrRk3PHI0y8ZDDhGr/qB85l7fdt8QbkdJtluN77N6O3QWa23Kgn2Ly1dObhvec3k0LSvcqxdiV5x2l5f7L1qHn1LYi0ha8bxOWxhJ07ydKUt0xpoPDI74KisIrdWFq5FyKnCmdnGowr1mQZNjdebXyo43/oT+v/QrdwoV8Fv+Ob1ZLmczfi9aRuvsZWgTxh4muMRbGZnarN1STklWx3aFUQDhxz1r0AGB38ZCJLKU/kHhaxX1BaMaGKtbHgyDKFZ+ZVFhVXi7wOtOm6FR0H/QIDAQAB

Signature sent in the header

X-Cliq-Signature : "jSYAaw+5Kd3PMF3PO5kpuMkwKn7++S9WJG2c0iB4kMnRYH1cdNldQPaLQ0DKxLMyzW/pY2XY6t2wtnviQ+qmARr+AQX9tyDnGOjbbxF/1A9JW1+5VwdB9pNVAC4Rjqp9iI9QdxFfMm7jaEn4P1BVJZ/3oB994/T8IJG3/rZPu4DtULEa0s81fLN8kRs4Ror87Pj2RmJuSm8cfCi9N38gqNSR9WGXA/GRycpWjVxFtCqROQmrR4CUBmEKrPl31xR9ascY/IBcjxQXoSLnvz0T/RPkUptqBDBjiJQ57Tq6w6jAkVSyxV4LiAdTj1cmTG28QLjNeyhpfuugTpzjpi3MBQ=="

Request body

{
   "name": "urlinvokeextension",
   "handler": {
      "type": "execution_handler"
   },
   "response_url": "https://cliq.zoho.com/v2/extensions/2305843009213696807/responses/17202824105415695206907020",
   "type": "command",
   "timestamp": 1569520690703,
   "params": {
      "environment": {
         "data_center": "US"
      },
      "access": {
         "user_id": "651652091",
         "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:69.0) Gecko/20100101 Firefox/69.0",
         "chat_id": "CT_2243226337559778047_661211447-B2"
      },
      "mentions": [],
      "options": {},
      "selections": [],
      "arguments": ""
   }
}

Sample verification code

Node.js


var publicKey = ....;
var signature = ....;
var verifier = crypto.createVerify('sha256');
verifier.update(bodyString);
var result = verifier.verify(publicKey, signature, 'base64');

Java


String publicKeyString = ...;
String signatureString = ...;
byte[] bytes = Base64.decodeBase64(publicKeyString);
X509EncodedKeySpec ks = new X509EncodedKeySpec(bytes);
KeyFactory kf = KeyFactory.getInstance(KEYPAIR_ALGORITHM);
PublicKey publicKey = kf.generatePublic(ks);
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initVerify(publicKey);
signature.update(text.getBytes("UTF-8"));

boolen result = signature.verify(Base64.decodeBase64(signatureString));

Webhook based extensions

What are extensions in Cliq ?