Exploring Kaizala WebHooks

Webhooks allow you to build or integrate applications which subscribe to certain events on Kaizala. When one of those events is triggered, Kaizala service would send a HTTPS POST payload to the webhook’s configured URL. Webhooks can be used to listen to content being posted on the group and use that information to update your database, trigger workflows in your internal systems, etc. You could also do the reverse, wherein post content on Kaizala based on an internal event in your system using the Kaizala APIs (refer this post).

There were few enhancements that were added to WebHooks post my initial blog post. Please go through the APPENDIX section to read about callback URL validation and callBackHeaders in the WebHook callback.

Requirements

Below are the requirements that the URL should comply with to be used to register a webhook on Kaizala:

  • Support for HTTPS Post (HTTP endpoints are not supported)
  • The URL should accessible over the internet
  • The callback payload (Request Body) would be a JSON – you will have to parse the JSON content to get the data of interest

Events

When configuring a webhook, you can choose which events you would like to receive payloads for. There are 2 levels at which you can subscribe for events:

  • Group – allows you to listen to event(s) in a group
  • Action package – allows you to listen to event(s) for an action package across all groups in Kaizala
  • Action – allows you to listen to event(s) for an action (instance of an action package / Kaizala actions)

Only subscribing to the specific event(s) you plan on handling is useful for limiting the number of HTTP requests to your server. To change the list of subscribed events, you could delete / unsubscribe to the previously configured webhook and configure a new one.

The events for which you could subscribe are ActionCreated, ActionResponse, SurveyCreated, JobCreated, SurveyResponse, JobResponse, TextMessageCreated, AttachmentCreated, Announcement, MemberAdded, MemberRemoved, GroupAdded, GroupRemoved. [refer the Microsoft documentation here for updated event list as well as parameter information].

The webhook API endpoints are available in the Kaizala API Postman collection under [5.0] Subscription APIs (webhooks).

Webhook postman collection

Example

NOTE: The request inspector https://requestb.in I have used below has been discontinued. You could use other similar services instead (e.g: https://webhook.site).

For a demo, let’s register a webhook to subscribe for the TextMessageCreated event. We will be using a publicly available request inspector (https://requestb.in) to generate a URL to use for registering the webhook.

We’ll follow the below steps:

  • Step 1 – Create a RequestBin URL
  • Step 2 – Get the id of the Kaizala group
  • Step 3 – Register a webhook (for TextMessageCreated event)
  • Step 4 – Send a text message on Kaizala
  • Step 5 – Observe the webhook payload

Step 1 – Create a RequestBin URL

Go to https://requestb.in to create a RequestBin URL

creating requestbin

Step 2 – Get the id of the Kaizala group

To register a webhook on a group, you need to be an admin of the group. The group id is present in the URL of the group.

Group-id

Step 3 – Register a webhook (for TextMessageCreated event)

Before running the below, make sure you have a valid accessToken (you can run Step1, Step2, Step3 from [1.0] Authentication folder)

Enter the group id and the RequestBin URL in the Request body and hit Send. If successful, you should get a 200 OK and a webhookId in the response. (Save this webhookId – you will need it in case you want to delete / unsubscribe the webhook).

Registering-webhook-postman

Step 4 – Send a text message on Kaizala

Send a text message on the group to which you have registered the webhook. Below is a snapshot of the test message on my phone.

text-message-kaizala

Step 5 – Observe the webhook payload

Refresh the RequestBin URL to see the webhook callback payload [the page for me was https://requestb.in/wcduftwc?inspect]

RequestBin url refresh

The JSON seen is the webhook callback payload you would receive for a TextMessageCreated event. While integrating with your systems, you could parse this JSON and take the requisite action. Pasting the formatted JSON from the payload below for reference.

{  
    "objectId":"b30d58b2-a95b-43eb-8fcf-71773b7528b5",
    "objectType":"Group",
    "eventType":"TextMessageCreated",
    "eventId":"b44380a8-27fc-4463-84da-f918c6c3a0b2",
    "data":{  
       "text":"A message to test Kaizala webhook!"
    },
    "fromUser":"+91XXXXXXXXXX",
    "fromUserName":"XXXXXXX ",
    "fromUserProfilePic":"https://mobi.blob.core.windows.net/...9da685.jpg"
}

In case you face any difficulties / have any feedback, feel free to reach out to me through the contact page. Thank you for reading – happy integrating!

APPENDIX

There are few changes that were made after I wrote this post, detailing them below.

callBackUrl validation

Starting 24th June 2018, WebHook registration involves validating the callBackUrl (documented at https://docs.microsoft.com/en-us/kaizala/breakingchanges#validation-of-registered-callbackurl-when-webhook-is-created). Only after the validation passes, would the webhook be registered.

  • Callback URL / endpoint / method / handler will need to support both GET and POST calls (GET for validation and POST for receiving the data from Kaizala)
  • While you register a webhook, Kaizala service would do a GET request to the callBackUrl with validationToken as a query string parameter
  • Your method should return the validationToken in the response body as plain text

Below is a screenshot of a C# MVC handler:

Webhook validationToken

Custom headers support in WebHook callback

There are scenarios where the API endpoint is on a service that needs certain headers as a part of the request (without which the request to the endpoint would not go through). For these cases, you could use the callBackHeaders dictionary while registering a WebHook. Below is an example for callBackHeaders.

"callBackHeaders" : {
"X-Client-Id":"xyzabc4-aabb-4cfx-9020-f1fcdxb9x4xd",
"X-Client-Secret":"uL6awebM2bixwK8qizpU0diuT1rW4yS8xF3iJ7lS8xH2kF2cV",
"Authorization":"Basic QWxhZGxzrRpbjpvxtcGV2FwtZQ=="
}

Will keep this post updated with other changes that may come in. Stay tuned!

3 thoughts on “Exploring Kaizala WebHooks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s