Exploring Kaizala WebHooks

Kaizala Developer Platform team

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.

Requirements

Following 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://putsreq.com or https://hookbin.com/).

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!

 

Feedback usabilla icon