用于注册 & 管理 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"
}
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈