Web 开发者通常使用 Webhook 来调用另一个系统中的行为。例如,Webhook 可用于:
您必须是管理员或具有权限的自定义用户角色的专员才能创建 Webhook。试用帐户最多可创建 10 个 Webhook,速率限制为每分钟 60 次调用。
关于 Webhook
有两种方法可以将 Webhook 和 Zendesk Support 中的活动连接起来:
- 为 Webhook 订阅一个或多个 Zendesk 事件。使用这种连接方法可以根据组织、用户、专员空闲状态、帮助中心或社区活动发送请求。有关受支持事件类型的列表,请参阅 API 参考中的 Webhook 事件类型。
- 将 Webhook 连接到触发器或自行程序。使用这种连接方法可以根据工单活动发送请求。
已订阅 Zendesk 事件的 Webhook 无法连接触发器或自行程序。同样,已连接触发器或自行程序的 Webhook 无法订阅 Zendesk 事件。现有 Webhook 的连接方法无法更改。
订阅 Zendesk 事件
订阅了一个或多个 Zendesk 事件的 Webhook 始终使用 POST HTTP 方法发送请求。该请求包括一个包含事件相关数据的 JSON 有效负载。您无法更改请求的 HTTP 方法或有效负载。有关事件有效负载架构的更多信息,请参阅 API 参考中的 Webhook 事件类型。
连接触发器或自行程序
-
JSON
-
XML
-
表格编码内容
当您将 Webhook 连接到触发器或自行程序时,您可以定义请求的内容。对于以 JSON 或 XML 请求格式使用 POST、PUT 或 PATCH HTTP 方法的 Webhook,其内容就是请求的有效负载。使用其他 HTTP 方法或格式的 Webhook 不包含请求有效负载。又或者,您可以添加自定义 URL 参数作为两个键值字符串的数组。在定义请求有效负载或 URL 参数时,您可以使用任何可用的内容占位符将工单数据插入到请求中。
Webhook 的请求有效负载或 URL 参数必须小于 256 KB。
Webhook 排序和重试
事件、触发器或自行程序在调用 Webhook 时会将要运行的 Webhook 作业排在队列中,但不会实际立即运行作业。Webhook 作业是独立运行的,因此无法保证 Webhook 会以特定的顺序执行。
如果端点返回某些 HTTP 响应代码,Webhook 请求将自动重试最多 3 次。和目标不同,连续失败的请求不会取消激活 Webhook。有关重试场景的更多信息和示例,请参阅我们开发者文档中的监测 Webhook。
创建 Webhook
您可以在管理中心创建 Webhook。
创建 Webhook 的步骤
- 在管理中心,单击侧栏中的应用和整合 (),然后选择操作和 Webhook > Webhook。
- 单击创建 Webhook。
- 要为 Webhook 订阅一个或多个 Zendesk 事件,请选择 Zendesk 事件,然后在下拉菜单中选择一个或多个事件类型。
- 要将 Webhook 连接到触发器或自行程序,请选择触发器或自行程序。
- 单击下一步。
- 输入 Webhook 的名称和描述。
- 输入用于和第三方服务或系统整合的端点 URL。请参阅 Webhook 端点。
当设置 Webhook 以和第三方整合时,您可能需要查阅第三方的文档。
- 选择 Webhook 的请求方法和请求格式。
- 选择 Webhook 的身份验证方法,并提供所需的任何其他信息。请参阅对您的 Webhook 进行身份验证。
- (可选)单击添加标头以添加自定义标头,然后输入标头名称和值。要添加更多标头(最多四个),请单击添加更多标头。请参阅自定义 Webhook 标头。注意:请勿在自定义标头中包含敏感信息。
- (可选)单击测试 Webhook,以确保其正常运行。
- 单击创建 Webhook以创建 Webhook。
- 对于触发器和自行程序 Webhook,您必须将 Webhook 连接到触发器或自行程序。请参阅将 Webhook 连接到 Support 触发器或自行程序。连接触发器或自行程序后,返回创建 Webhook页面,然后单击完成设置。
创建 Webhook 后,您可以在管理中心的 Webhook 页面查看其详情、订阅和活动。请参阅管理 Webhook。
Webhook 端点
Webhook 会将请求发送到您在创建时指定的端点 URL。端点 URL 使用以下格式:https://www.yourdomain.com/path
。
尽管不是必需的,但建议使用安全 HTTP (HTTPS)。通过提供安全的端点 URL,您可以启用身份验证并安全地传递数据。
自定义 Webhook 标头
通过自定义标头可以在 Webhook 发送的请求中包含更多信息,并使其更易于连接一些对 Webhook 标头具有特殊要求的第三方服务。请注意自定义标头的以下要求和限制:
- 要使用自定义标头,您必须使用安全 (HTTPS) 端点 URL。
- 请勿在自定义标头中加入身份验证凭证或其他敏感信息。请改用受支持的身份验证方法。
- 标头名称必须是唯一的,并且不能超过 128 个字符。支持所有字母数字 US ASCII 字符,以及以下符号:
!
、#
、$
、%
、&
、'
、*
、+
、-
、.
、^
、_
、`
、|
、和~
。 - 标头值的最大长度为 1,000 个字符,支持从 0x20 到 0x7E 的所有 US ASCII 字符。
- 不支持以下标头:
- accept-charset
- accept-encoding
- connection
- content-encoding
- content-length
- content-md5
- content-type
- date
- expect
- forwarded
- host
- keep-alive
- max-forwards
- origin
- proxy-authenticate
- referer
- server
- te
- trailer
- transfer-encoding
- upgrade
- user-agent
- via
- www-authenticate
- zendesk-api-version
- zendesk-ep
- 此外,标头不能以下列前缀开头:
- access-control
- x-amzn
- x-apigw
- x-datadog
- x-envoy
- x-forwarded
- x-zendesk
对 Webhook 进行身份验证
如果您的 Webhook 要与安全端点整合,有三个选项可用于对该 Webhook 及其发送的数据进行身份验证。您可能需要参考关于端点身份验证要求的第三方文档,或与您团队中的开发者合作,以确定您 Webhook 的正确身份验证方法。
- 不需要:不配置或不需要进行身份验证。
- API 密钥:使用 API 密钥对 Webhook 进行身份验证。
- 基本身份验证:使用用户名和密码对 Webhook 进行身份验证。
- 不记名令牌:使用 OAuth 访问密钥对 Webhook 进行身份验证。
如果您的开发者想要了解更多关于 Webhook 身份验证的信息,请参阅 Webhook 安全与身份验证。
为了提高安全性,您还可以验证 Webhook 的签名。有关更多信息,请参阅对 Webhook 进行身份验证。
将 Webhook 连接到触发器或自行程序
要调用触发器和自行程序 Webhook,必须先将其与触发器或自行程序连接。触发器和自行程序指定了应在何种情况下调用 Webhook。
将 Webhook 连接到 Support 触发器的步骤
测试 Webhook
在管理中心,您可以选择使用不同的事件源和请求测试 Webhook。除了访问现有的专门用于测试的 Webhook 之外,您还可以在创建或编辑期间测试 Webhook。
测试 Webhook 的步骤
- 在管理中心,单击侧栏中的应用和整合 (),然后选择操作和 Webhook > Webhook。
- 在列表中找到该 Webhook,单击 Webhook 所在行的选项菜单图标 (),然后单击测试 Webhook。
- 在测试 Webhook 面板中,选择要测试的事件。这是一个可用于测试端点 URL 的示例请求。
- 输入您的测试请求详情:请求正文、参数或标头。
- 单击发送测试。响应会显示在测试请求下方的面板中。