在数字化办公中，ONLYOFFICE 协作空间作为一款功能强大的文档协作平台，提供了丰富的自动化功能。对于开发者而言，Webhook 触发器是实现业务流程自动化与系统集成的关键工具。本文将深入探讨如何在 ONLYOFFICE 协作空间中高效利用 Webhook，实现智能工作流。
什么是 ONLYOFFICE 协作空间
ONLYOFFICE 协作空间供了一个基于房间的文档协作环境，让您在专用空间中存储和管理个人文档，旨在提升办公文档和其他内容的协作效率，让用户能够与同事、客户、合作伙伴、承包商、赞助商等多方人员顺畅协作。设置灵活的访问权限和用户角色设置，可支持用户对整个或单独房间的访问权限调整。开发者版本更是支持集成至您品牌下的商业软件和服务器，帮您定制扩展功能。
什么是开发者版 ONLYOFFICE 协作空间？无缝集成至您的软件和服务器
什么是 Webhook
Webhook 是一种灵活的“回调”机制，基于 HTTP/HTTPS 协议，可在特定事件发生时触发。它能够将信息传递给外部服务，实现不同系统间的无缝对接与联动。Webhook 可以用于以下核心场景：
-
数据实时同步：在多系统协同办公场景下，Webhook 可以将协作空间中的文件状态、用户信息等数据实时更新至其他业务系统，如项目管理工具或客户关系管理系统，消除数据孤岛。
-
自动化业务流程：当特定文件夹内上传新文件时，自动触发外部脚本进行内容审核、格式转换或备份操作；新用户注册协作空间时，同步在企业内部通讯录或权限管理系统中创建对应账号。
-
监控与警报：结合监控平台，利用 Webhook 在文件删除、权限变更等敏感操作发生时发送通知，及时发现并处理潜在风险。
在协作空间中设置Webhook
1. 创建 Webhook
登录ONLYOFFICE协作空间，找到开发者工具，进入 Webhook 设置界面。
注：管理员既可以使用左侧的开发者工具链接，也可以通过点击左下角的选项图标菜单，选择设置 -> 开发者工具选项，切换到此部分。
点击创建 Webhook，开始创建新的 Webhook 触发器，并设置以下参数：
-
Webhook名称：便于管理的标识名称。
-
Payload URL：Webhook 发送到的端点地址，必须对HEAD方法的HTTP请求响应200状态。
-
密钥：用于验证发送到 Payload URL 的请求。输入自己的密钥或点击生成。
-
SSL验证：默认启用，不建议禁用。
-
触发器：选择特定事件或发送所有内容。
-
目标ID：标识用户、组、文件或文件夹，以便跟踪对象的更改。
根据设置，创建的 Webhook 将被分配给所有协作空间事件或仅选定的触发器 / 多个触发器。您将在外部服务中收到有关协作空间事件的自动通知。在创建特定 Webhook 时选择的触发器仅在 Webhook 所有者有权访问修改后的协作空间实体时才会被触发。
2. 管理Webhook
-
使用切换开关禁用或重新启用 Webhook。
-
使用选项图标更改设置、查看历史记录或删除 Webhook。
-
查看历史记录时，可以通过交付日期或状态筛选 Webhook，并使用重试选项重新传递选定的 Webhook 。
3. 验证请求真实性
Webhook 收到请求时，需验证其真实性，防止恶意调用。协作空间采用密钥签名机制保障数据安全。例如，在 Node.js 中，可以通过以下代码验证签名：
const crypto = require('crypto');
function getSecretHash(secretKey, body) {
const hasher = crypto.createHmac('sha256', Buffer.from(secretKey, 'utf8'));
hasher.update(Buffer.from(body, 'utf8'));
return hasher.digest('hex').toUpperCase();
}密匙包含在 x-docspace-signature-256 标头中：
{
"Accept": ["*/*"],
"x-docspace-signature-256": ["sha256=0D4C9D09136103625379E0BC3AA6084E941EA2F2901A2C94FACEFE3A7F9688F3"]
}通过对比计算出的签名与接收到的签名，可精准判断请求是否来自可信的源头。
4. Webhook请求与响应机制
Webhook 请求体承载关键信息：
-
触发器详情 ：明确告知是何种事件引发此次数据发送，例如具体是哪个文件被上传或哪个用户被创建等。
-
上下文信息 ：涵盖 Webhook 执行时所处的环境数据，如当前用户身份、时间戳等，为后续处理提供丰富背景。
-
实体匿名数据 ：对被修改实体（文件、文件夹、用户等）进行匿名化处理后的数据，既保证数据可用性，又兼顾隐私安全。
若请求初次失败，ONLYOFFICE 协作空间会启动重试机制，最多尝试5次。重试间隔遵循2的尝试次数次方秒规则。每次重试，请求体都会补充如下信息：
-
retryCount ：已尝试发送的次数。
-
retryOn ：本次重试的时间戳。
-
lastFailureOn ：上一次请求失败的具体时间。
-
lastFailureContent ：上次失败的详细错误内容。
-
lastSuccessOn ：该 Webhook 最近一次成功请求的时间。
此外，若响应返回 410 Gone 状态码，协作空间会自动移除对应 Webhook；若 5 次重试均失败且距离上次成功请求超三天，则会禁用该 Webhook，避免无效请求持续占用资源。
对于 Webhook 响应，协作空间要求相对宽松。响应体只需符合数据库文本大小限制，且无需签名。
5. Webhook队列处理
所有新创建的 Webhook 会被添加至队列，系统每5秒检查一次待处理队列，并最多启动10个线程并行发送 Webhook。这意味着多个 Webhook 可同时处理，但发送顺序可能与事件发生顺序存在差异，开发者在设计业务逻辑时需考虑这一特性，确保流程的正确性与稳定性。
6. 测试Webhook
要测试 Webhook 的运行，可以使用第三方服务。 例如，您可以从 Webhook.site 服务获取一个唯一 URL，并在创建网络钩子时在有效 Payload URL 字段中指定该 URL。 在门户网站上执行触发器时，将向指定地址发送请求，请求中的信息将显示在网站界面上。
立即在 ONLYOFFICE 中使用 Webhook
欢迎在评论区分享您的使用经验或建议。如果您尚未尝试，希望本文的介绍能为您提供一些参考。您可以通过下方链接访问我们的官网，亲自体验一下这一功能，更多高效的应用技巧期待您来探索！
