Webhooks
简介
Webhook 允许使用 http/https 回调通知预配置的接收方关于门户上的事件。用户可以配置 webhook,使门户事件触发外部服务的操作。此方法可用于同步和跟踪特定事件。
使用 webhook 根据 ONLYOFFICE 协作空间中的各种事件在您使用的任何应用程序或网站端执行自定义操作。
您可以创建和管理所有 webhook,配置它们,并浏览每个 webhook 的历史记录以审计其性能。
创建新 webhook
首先,您需要在外部服务内设置 webhook 端点。此端点将用于侦听协作空间 webhook 并接收事件通知。
创建并配置端点后,您可以在协作空间中创建 webhook。要创建新 webhook ,
- 通过点击任何板块(空间、文档)左侧面板上的开发者工具链接打开开发者工具板块。
默认情况下,除访客外的所有用户均可访问开发者工具板块,因此任何用户均可访问此页面并创建自己的 webhook 。管理员可以看到所有创建的 webhook,而用户只能看到自己的 webhook 。
管理员既可以使用左侧的开发者工具链接,也可以通过左下角的
菜单切换到协作空间设置,然后选择设置 -> 开发者工具选项。
- 在开发者工具中,转到 Webhooks 板块。
- 点击创建 webhook 按钮。
-
设置必要参数:
- Webhook 名称 - 用于在门户上方便使用 webhook 的标识名称。
- 有效载荷 URL - webhook 应发送到的端点地址。
- 密钥 - 设置 webhook 密钥以验证发送到有效载荷URL的请求。输入您自己的密钥或点击生成。请注意:密钥保存后无法再次检索。如果丢失或忘记此密钥,可以重置它,但使用此密钥的所有集成都需要更新。
- SSL 验证 - 默认启用此选项以在交付有效载荷时验证SSL证书。不建议禁用此参数。
- 触发器 - 使用发送全部选项或选中单独事件单选按钮并仅选择特定触发器,例如用户、群组、文档、文件夹和空间等门户实体的更改事件。例如用户创建、邀请、更新、删除等。
- 目标 ID - 用户、群组、文件或文件夹的标识符,允许您跟踪单个对象的更改。
- 有效载荷 URL 必须对使用 HEAD 方法的 http 请求返回状态 200。
- 点击创建按钮。
根据设置,创建的 webhook 将分配给所有协作空间事件或仅选定的触发器/若干触发器。您将在外部服务中收到有关协作空间事件的自动通知。为特定 webhook 在创建期间选择的触发器仅在 webhook 所有者对被修改的协作空间实体拥有访问权限时触发。
管理 Webhooks
您可以使用创建好的 webhook 旁边的开关将其禁用或重新启用。使用右侧的 图标可更改创建时指定的 webhook 设置、查看 webhook 历史记录或删除该 webhook。


查看历史记录时,您可以按交付日期或状态(未发送、2XX、3XX、4XX、5XX)过滤webhooks。点击 过滤按钮,选择必要的参数并点击应用。
您可以在列表中选择一个或多个 webhook,并使用顶部出现的 重试选项来重新交付选定的 webhooks。或者点击特定 webhook 旁边的
图标,在上下文菜单中选择
重试选项。


点击特定 webhook 旁边的 图标,在上下文菜单中选择
Webhook详情选项。


以下详细信息可用:
- 状态 – 响应状态。
- 事件ID – 事件的ID。
- 触发器 – 导致 webhook 被激活的触发器。
- 事件时间 – 事件发生的日期。
- 交付时间 – 从端点收到响应的日期。
在请求/响应板块中,您还可以查看POST请求头、POST请求正文、POST响应头和POST响应正文。使用 图标可将请求或响应的头/正文复制到剪贴板。
使用 Webhook 详情标题旁边的 图标可重新交付该 webhook。
技术细节
使用以下两个服务进行工作:
- ASC.Web.Studio提供发送 webhooks 的方法,启动WorkerService。
WorkerService – 订阅接收来自消息代理(例如,默认使用RabbitMQ)的消息,该代理存储有关等待发送的新 webhooks 的信息。从代理收到的消息被放入队列,之后该队列被不断查询并异步联系ASC.Webhooks.Service以发送 webhooks。
- ASC.Webhooks.Core提供将 webhooks 发布到数据库和消息代理的方法,以及处理数据库的方法。
有关 ONLYOFFICE 协作空间API的更多详情,请参阅 api.onlyoffice.com网站。