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.


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


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).


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

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.

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).

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.

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]

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!


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:

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!

12 thoughts on “Exploring Kaizala WebHooks

  1. This blog is really helpful. 🙂

    I have question what url do i need to pass while creating RestClient object in CallbackHandler() method.
    Is this my API url or anything else?


  2. Hi,
    I am trying this out but now it seems it has a validationToken going on.
    And to be honest, I think it is broken somehow. I have used this link to test and make sure the validationToken is being returned: https://putsreq.com/rq2YbGBVvmV9HUrnWzzF/inspect
    Even though it returns the validationToken correct, I still get this error message:
    “message”: “Callback URL couldn’t be validated”,
    “errorCode”: “InvalidParameters”,
    “errorCategoryKey”: “InvalidParametersException”


    1. I am having similar problem. I have used custom call back handler and do have POST and GET services and returning validationToken in the Get. I received same error when I am trying to do webhook.


  3. In the line “string x = Request.QueryString[“validationToken”];” —
    Is the “validationToken” keyword predefined?


  4. Hello Gladson,
    I’ve been working with this guide, and all the 3 steps for authentication worked fine, but when I want to subscribe on a group/action level, I get the following message:

    “message”: “Token doesn’t have permission to access the endpoint!”,
    “errorCode”: “InsufficientPermissions”,
    “errorCategoryKey”: “AuthException”

    I am Admin of the groups and made the Action cards myself. Is there any other permissions I’m missing? Do I have to be Tenant Admin?



Leave a Reply