跳到主要内容

Webhooks

简介​

Webhook 允许使用 http/https 回调通知预配置的接收方关于工作空间中的事件。用户可以配置 webhook，使工作空间中的事件触发外部服务的操作。此方法可用于同步和跟踪特定事件。

使用 webhook 根据 ONLYOFFICE Apps中的各种事件在您使用的任何应用程序或网站端执行自定义操作。

您可以创建和管理所有 webhook，配置它们，并浏览每个 webhook 的历史记录以审计其性能。

创建新 webhook​

首先，您需要在外部服务内设置 webhook 端点。此端点将用于侦听工作空间 webhook 并接收事件通知。

创建并配置端点后，您可以在工作空间中创建 webhook。要创建新 webhook，

  1. 通过点击任何板块(文件、房间、表单)左侧面板上的开发者工具链接打开开发者工具板块。

    备注

    默认情况下，除访客外的所有用户均可访问开发者工具板块，因此任何用户均可访问此页面并创建自己的 webhook。管理员可以看到所有创建的 webhook，而用户只能看到自己的 webhook。

    管理员既可以使用左侧的开发者工具链接，也可以通过左下角的 选项图标 菜单切换到工作空间设置，然后选择设置 -> 开发者工具选项。

  2. 在开发者工具中，转到 Webhook 板块。

  3. 点击创建 webhook 按钮。

  4. 设置必要参数：

    使用 webhooks

    • Webhook 名称 - 用于在工作空间中方便使用 webhook 的标识名称。

    • 有效载荷 URL - webhook 应发送到的端点地址。

    • 密钥 - 设置 webhook 密钥以验证发送到有效载荷URL的请求。输入您自己的密钥或点击生成。请注意：密钥保存后无法再次检索。如果丢失或忘记此密钥，请打开 webhook 设置并点击重置密钥链接以生成新密钥。所有使用先前密钥的集成都需要更新。

      Webhook 设置

    • SSL 验证 - 默认启用此选项以在交付有效载荷时验证SSL证书。不建议禁用此参数。

    • 触发此 webhook 的事件 - 使用发送全部选项或选中单独事件单选按钮并仅选择特定触发器，例如用户、群组、文件、文件夹、房间、表单和 AI 智能体等工作空间实体的更改事件。例如用户创建、邀请、更新、删除等。

    • 目标 ID - 用户、群组、文件或文件夹的标识符，允许您跟踪单个对象的更改。

    使用 webhooks

  5. 有效载荷 URL 必须对使用 HEAD 方法的 http 请求返回状态 200。

  6. 点击创建按钮。

根据设置，创建的 webhook 将分配给所有工作空间事件或仅选定的触发器/若干触发器。您将在外部服务中收到有关工作空间事件的自动通知。为特定 webhook 在创建期间选择的触发器仅在 webhook 所有者对被修改的工作空间实体拥有访问权限时触发。

管理 Webhooks​

已创建的 webhook 会列出其名称、作者、有效载荷 URL 和状态。您可以使用状态列中的开关禁用或重新启用 webhook。使用右侧的 选项图标 图标打开包含以下选项的上下文菜单：

使用 webhooks

  • 设置 - 更改创建时指定的 webhook 设置。
  • Webhook 历史记录 - 查看 webhook 的交付历史记录。
  • 删除 webhook - 删除该 webhook。

点击 webhook 即可查看 webhook 历史记录

使用 webhooks

查看历史记录时，您可以按交付日期或状态（未发送、2XX、3XX、4XX、5XX）过滤webhooks。点击 过滤图标 过滤按钮，选择必要的参数并点击应用。

使用 webhooks

您可以在列表中选择一个或多个 webhook，并使用顶部出现的 重试图标 重试选项来重新交付选定的 webhooks。或者点击特定 webhook 旁边的 选项图标 图标，在上下文菜单中选择 重试图标 重试选项。

使用 webhooks

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

使用 webhooks

以下详细信息可用：

  • 状态 – 响应状态。
  • 事件ID – 事件的ID。
  • 事件类型 – 导致 webhook 被激活的事件。
  • 事件时间 – 事件发生的日期。
  • 交付时间 – 从端点收到响应的日期。

在请求/响应板块中，您还可以查看POST请求头、POST请求正文、POST响应头和POST响应正文。使用 复制图标 图标可将请求或响应的头/正文复制到剪贴板。

使用 Webhook 详情标题旁边的 重试图标 图标可重新交付该 webhook。

技术细节​

使用以下两个服务进行工作：

  1. ASC.Web.Studio提供发送 webhooks 的方法，启动WorkerService。

    WorkerService – 订阅接收来自消息代理（例如，默认使用RabbitMQ）的消息，该代理存储有关等待发送的新 webhooks 的信息。从代理收到的消息被放入队列，之后该队列被不断查询并异步联系ASC.Webhooks.Service以发送 webhooks。

  2. ASC.Webhooks.Core提供将 webhooks 发布到数据库和消息代理的方法，以及处理数据库的方法。

有关 ONLYOFFICE Apps API 的更多详情，请参阅 api.onlyoffice.com网站。