用于注册 & 管理 Webhook 的 API
/webhook
用于管理 Kaizala 内事件订阅的 API 终结点。
WebHook 是一种轻型 HTTP 模式,提供简单的发布者/订阅者模型,用于将 Web API 和 SaaS 服务连接在一起。 当 Kaizala 中发生事件时,会以 HTTP POST 请求的形式向已注册的订阅者发送通知。 POST 请求包含有关事件的信息,使接收方能够采取相应措施。
使用 WebHook,可以订阅 Kaizala 中的会话组上下文中发生的各种事件。
POST /webhook
POST {endpoint-url}/v1/webhook
为了确保 Webhook 服务终结点是真实的且正常工作,我们将在创建订阅之前验证回调 URL。 为了进行验证,我们将向你发送一个验证令牌,你需要在 5 秒内向我们发送该令牌。 阅读更多
请求参数
参数 | 类型 | 选? | 说明 | |||||||
---|---|---|---|---|---|---|---|---|---|---|
HTTP 标头 | accessToken | 字符串 | 否 | 从身份验证终结点接收的访问令牌 | HTTP 标头 | Content-Type | String | 否 | “application/json” |
请求正文
参数 | 类型 | 选? | 说明 |
---|---|---|---|
objectId | 字符串 | 否 | 表示需要在其中创建 Webhook 的上下文的 对象的标识符。对于 ObjectType=Group,其组的标识符,For ObjectType=Action,其 actionId,For ObjectType=ActionPackage,其 action-package-id |
objectType | 字符串 | 否 | 枚举:“Group”/“Action”/“ActionPackage” |
eventTypes | Array | 否 | 需要订阅 Webhook 的不同类型的事件数组。 支持的事件包括:“ActionCreated”、“ActionResponse”、“SurveyCreated”、“JobCreated”、“SurveyResponse”、“JobResponse”、“TextMessageCreated”、“AttachmentCreated”、“Announcement”、“MemberAdded”、“MemberRemoved”、“GroupAdded”、“GroupRemoved” |
callBackUrl | 字符串 | 否 | 订阅的事件需要通知到的 HTTPS URL |
callBackToken | 字符串 | 是 | 可设置的可选参数,该参数将在 HTTP 标头“kz-callback-token”中发送,其中包含 WebHook 发出的每个 callBack |
callBackContext | 字符串 | 是 | 可以设置的可选参数,该参数将在 JSON 有效负载中作为“上下文”发送,其中包含 WebHook 发出的每个调用回叫 |
有效性 | 字符串 | 是 | 以 EPOCH 格式处于活动状态的 WebHook 的有效性。 默认值为 2 年 |
响应正文
参数 | 类型 | 说明 |
---|---|---|
webhookId | String | 表示创建的 WebHook 的标识符 |
请求正文 - 订阅组级别的所有事件
{
"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"
}
可 在此处找到 Kaizala 中已注册事件的 Webhook 响应架构。
注意: Kaizala 保证至少传递一次 Webhook 响应。 在某些情况下,Kaizala 可能会针对同一事件发送重复的 Webhook 响应。
获取 /webhook
GET {endpoint-url}/v1/webhook
请求参数
参数 | 类型 | 选? | 说明 | |
---|---|---|---|---|
HTTP 标头 | accessToken | 字符串 | 否 | 从身份验证终结点接收的访问令牌 |
查询参数 | objectId | 字符串 | 否 | 表示需要在其中创建 Webhook 的上下文的 对象的标识符。对于 ObjectType=Group,其组的标识符,For ObjectType=Action,其 actionId,For ObjectType=ActionPackage,其 action-package-id |
查询参数 | objectType | 字符串 | 否 | 枚举:“Group”/“Action”/“ActionPackage” |
响应正文
参数 | 类型 | 说明 |
---|---|---|
webhook | JSON 对象数组 | 在 objectId 上订阅的 Webhook 数组 |
数组 webhooks[]中每个 Webhook 的 JSON 结构:
参数 | 类型 | 说明 |
---|---|---|
id | String | Webhook 标识符 |
objectId | String | 对象标识符 |
objectType | String | 枚举:“Group”/“Action”/“ActionPackage” |
events | String[] | 事件列表,每个值都为“ActionCreated”、“ActionResponse”、“SurveyCreated”、“JobCreated”、“SurveyResponse”、“JobResponse”、“TextMessageCreated”、“AttachmentCreated”、“Announcement”、“MemberAdded”、“MemberRemoved”、“GroupAdded”、“GroupRemoved” |
callBackUrl | String | 需要将订阅事件通知到的回调 URL |
callBackToken | String | 将在 HTTP 标头“kz-callback-token”中发送的参数,其中包含 WebHook 发出的每个调用回叫 |
callBackContext | String | 在 JSON 有效负载中以“context”的形式发送的参数,其中 WebHook 发出的每个调用回叫 |
有效性 | String | 以 EPOCH 格式处于活动状态的 WebHook 的有效性。 |
积极 | 布尔值 | 如果 Webhook 的状态处于活动状态,则为 True |
示例 JSON 响应
{
"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
}
]
}
删除 /webhook
DELETE {endpoint-url}/v1/webhook
请求参数
参数 | 类型 | 选? | 说明 | |
---|---|---|---|---|
HTTP 标头 | accessToken | 字符串 | 否 | 从身份验证终结点接收的访问令牌 |
路径参数 | webhookId | 字符串 | 否 | Webhook 标识符 |
PUT /webhook
PUT {endpoint-url}/v1/webhook/{webhookId}
可以更新 Webhook 的任何参数。 根据需要,请求正文可以包含 1 个或多个参数。
请求参数
参数 | 类型 | 选? | 说明 | |
---|---|---|---|---|
HTTP 标头 | accessToken | 字符串 | 否 | 从身份验证终结点接收的访问令牌 |
路径参数 | webhookId | 字符串 | 否 | Webhook 标识符 |
请求正文
参数 | 类型 | 选? | 说明 |
---|---|---|---|
objectId | 字符串 | 是 | 表示需要在其中创建 Webhook 的上下文的 对象的标识符。对于 ObjectType=Group,其组的标识符,For ObjectType=Action,其 actionId,For ObjectType=ActionPackage,其 action-package-id |
objectType | 字符串 | 是 | 枚举:“Group”/“Action”/“ActionPackage” |
eventTypes | Array | 是 | 需要订阅 Webhook 的不同类型的事件数组。 支持的事件包括:“ActionCreated”、“ActionResponse”、“SurveyCreated”、“JobCreated”、“SurveyResponse”、“JobResponse”、“TextMessageCreated”、“AttachmentCreated”、“Announcement”、“MemberAdded”、“MemberRemoved”、“GroupAdded”、“GroupRemoved” |
callBackUrl | 字符串 | 是 | 订阅的事件需要通知到的 HTTPS URL |
callBackToken | 字符串 | 是 | 可设置的可选参数,该参数将在 HTTP 标头“kz-callback-token”中发送,其中包含 WebHook 发出的每个 callBack |
callBackContext | 字符串 | 是 | 可以设置的可选参数,该参数将在 JSON 有效负载中作为“上下文”发送,其中包含 WebHook 发出的每个调用回叫 |
有效性 | 字符串 | 是 | 以 EPOCH 格式处于活动状态的 WebHook 的有效性。 默认值为 2 年 |
活动 | Boolean | 是 | 如果值为 true,请将 Webhook 的状态更改为“活动” |
示例请求正文
{
"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"
}
自动禁用 Webhook
为了提高 Webhook 的可靠性,我们最近添加了重试和禁用逻辑。 注册到 Webhook 的回调 URL/终结点,如果无法访问或未使用 2xx (>=3xx) 以外的状态代码做出响应,则我们的服务将在 2 天内尝试以指数方式访问/重试 6 次。
如果仍失败 2 天,则将禁用相应的 Webhook,并且所有者需要使用 Put /webhook API 更新它,然后才能重新开始工作。 例如,对于
PUT {endpoint-url}/v1/webhook/{subscriptionId}
请求正文:
{
"Active": "true"
}
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈