APIs to register & manage webhooks
/webhook
API end-point to manage subscriptions to events inside Kaizala.
WebHooks is a lightweight HTTP pattern providing a simple publisher/subscriber model for wiring together Web APIs and SaaS services. When an event happens in Kaizala, a notification is sent in the form of an HTTP POST request to registered subscribers. The POST request contains information about the event which makes it possible for the receiver to act accordingly.
Using WebHooks, you can subscribe to various events that occur within a conversation group context in Kaizala.
POST /webhook
POST {endpoint-url}/v1/webhook
To ensure your webhook service endpoint is authentic and working we will verify your callback URL before creating subscription. For verification we will send you a validation token which you need to send us back within 5 seconds. Read More
Request Parameters
| Parameter | Type | Optional? | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| HTTP Header | accessToken | String | No | Access Token received from the auth end-point | HTTP Header | Content-Type | String | No | "application/json" |
Request body
| Parameter | Type | Optional? | Description |
|---|---|---|---|
| objectId | String | No | Identifier representing the object in which context the webhooks need to be created.For ObjectType=Group, its group's Identifier, For ObjectType=Action, its actionId, For ObjectType=ActionPackage, its action-package-id |
| objectType | String | No | Enum: "Group"/"Action"/"ActionPackage" |
| eventTypes | Array | No | Array of different types of events you need to subscribe the webhook to. Supported events are: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | String | No | HTTPS URL to which the subscribed events need to be notified to |
| callBackToken | String | Yes | Optional parameter you can set which will be sent in the HTTP header 'kz-callback-token' with every callBack made by the WebHook |
| callBackContext | String | Yes | Optional parameter you can set which will be sent in the JSON payload as 'context' with every callBack made by the WebHook |
| validity | String | Yes | Validity for the WebHook to be active in EPOCH format. Default is 2 years |
Response body
| Parameter | Type | Description |
|---|---|---|
| webhookId | String | Identifier representing the webHook created |
Request Body - Subscribe to all events at group level
{
"objectId":"74943849802190eaea3810",
"objectType":"Group",
"eventTypes":[
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"callBackUrl":"https://requestb.in/123",
"callBackToken":"tokenToBeVerifiedByCallback",
"callBackContext":"Any data which is required to be returned in callback"
}
You can find webhook response schema for registered events in Kaizala here.
Note: Kaizala guarantees at-least once delivery of webhook response. It may happen, in certain cases, that Kaizala may send duplicate webhook response for the same event.
Get /webhook
GET {endpoint-url}/v1/webhook
Request Parameters
| Parameter | Type | Optional? | Description | |
|---|---|---|---|---|
| HTTP Header | accessToken | String | No | Access Token received from the auth end-point |
| Query parameter | objectId | String | No | Identifier representing the object in which context the webhooks need to be created.For ObjectType=Group, its group's Identifier, For ObjectType=Action, its actionId, For ObjectType=ActionPackage, its action-package-id |
| Query parameter | objectType | String | No | Enum: "Group"/"Action"/"ActionPackage" |
Response body
| Parameter | Type | Description |
|---|---|---|
| webhooks | JSON Object Array | Array of webhooks subscribed on the objectId |
JSON structure for each individual webhook in the array webhooks[]:
| Parameter | Type | Description |
|---|---|---|
| id | String | Webhook Identifier |
| objectId | String | Object Identifier |
| objectType | String | Enum: "Group"/"Action"/"ActionPackage" |
| events | String[] | Event list with each value as one of "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | String | Callback URL to which the subscribed events need to be notified to |
| callBackToken | String | Parameter which will be sent in the HTTP header 'kz-callback-token' with every callBack made by the WebHook |
| callBackContext | String | Parameter sent in the JSON payload as 'context' with every callBack made by the WebHook |
| validity | String | Validity for the WebHook to be active in EPOCH format. |
| active | Boolean | True, if the state of webhook is active |
Sample JSON Response
{
"webhooks": [
{
"id": "dac6fccf-f2e9-4abc-94d7-793037e99da7",
"objectId": "b21405d1-4b10-4c46-bfa9-8338592f3782",
"objectType": "Group",
"events": [
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"filters": [],
"callbackUrl": "https://requestb.in/12786un1",
"callbackToken": "tokenToBeVerifiedByCallback",
"ts": 1505491564677,
"validity": 1568605416677
"active": true
}
]
}
Delete /webhook
DELETE {endpoint-url}/v1/webhook
Request Parameters
| Parameter | Type | Optional? | Description | |
|---|---|---|---|---|
| HTTP Header | accessToken | String | No | Access Token received from the auth end-point |
| Path parameter | webhookId | String | No | Webhook Identifier |
PUT /webhook
PUT {endpoint-url}/v1/webhook/{webhookId}
Any parameter for the webhook can be updated. Request Body may contain 1 or more parameters, as needed.
Request Parameters
| Parameter | Type | Optional? | Description | |
|---|---|---|---|---|
| HTTP Header | accessToken | String | No | Access Token received from the auth end-point |
| Path parameter | webhookId | String | No | Webhook Identifier |
Request body
| Parameter | Type | Optional? | Description |
|---|---|---|---|
| objectId | String | Yes | Identifier representing the object in which context the webhooks need to be created.For ObjectType=Group, its group's Identifier, For ObjectType=Action, its actionId, For ObjectType=ActionPackage, its action-package-id |
| objectType | String | Yes | Enum: "Group"/"Action"/"ActionPackage" |
| eventTypes | Array | Yes | Array of different types of events you need to subscribe the webhook to. Supported events are: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | String | Yes | HTTPS URL to which the subscribed events need to be notified to |
| callBackToken | String | Yes | Optional parameter you can set which will be sent in the HTTP header 'kz-callback-token' with every callBack made by the WebHook |
| callBackContext | String | Yes | Optional parameter you can set which will be sent in the JSON payload as 'context' with every callBack made by the WebHook |
| validity | String | Yes | Validity for the WebHook to be active in EPOCH format. Default is 2 years |
| Active | Boolean | Yes | Change the state of webhook to Active, if the value is true |
Sample Request Body
{
"objectId":"74943849802190eaea3810",
"objectType":"Group",
"eventTypes":[
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"callBackUrl":"https://requestb.in/123",
"callBackToken":"tokenToBeVerifiedByCallback",
"Active": "true"
}
Auto-Disable of Webhooks
To improve the Reliability of our Webhooks, we recently have added the Retry and Disabling Logic. The Callback Url/Endpoint registered with a webhook, if not reachable or does not respond with a status code other than 2xx (>=3xx), then our Service will try to reach/retry it for 6 times in an exponential way within a span of 2 Days.
If it is still failing for 2 days, then the corresponding Webhook will be disabled, and the owner needs to update it with the Put /webhook API before it starts working again. For e.g.
PUT {endpoint-url}/v1/webhook/{subscriptionId}
Request Body:
{
"Active": "true"
}
Feedback
Submit and view feedback for