【后端】回调接口说明

为什么要有回调接口？

石墨文档中台采用无状态架构设计，不会存储接入方的用户信息、文件信息、权限信息等敏感数据。在需要用到这些信息的时候，石墨服务端会通过对应的回调接口来实时获取。

这样做的好处是，接入方的用户、文件、权限等信息发生改变时，无需向石墨上报和同步信息，避免了潜在数据泄露风险和数据一致性风险。

此外，有一些信息是石墨文档中台主动发起并推送给接入方的，例如文件内容更新、文档协作者协同状态变化等。

正确实现和优化回调接口，是确保石墨文档集成成功的关键因素。建议接入方在设计阶段就充分考虑安全性、性能和可用性要求，确保为用户提供流畅、安全的文档协作体验。

回调接口机制详解

工作原理

回调接口分类

分类	触发方式	主要用途	典型场景
数据获取类	石墨被动调用	获取用户、文件、权限信息	用户身份验证、权限校验
事件推送类	石墨主动推送	通知业务事件发生	文档更新、协作状态变化

回调接口地址

回调接口地址由接入方通过接口自行设置：更新应用回调地址

回调凭证类型

回调接口存在不同的触发场景，因此需要通过不同的凭证类型进行身份验证。石墨服务端会在 HTTP Header 中指定 X-Shimo-Credential-Type 来标识凭证类型。

凭证类型概览

凭证类型	数值	触发场景	验证方式	典型用例
文档用户操作触发	0	用户主动操作	Token 验证	打开文档、编辑内容、权限校验
石墨系统主动触发	3	石墨中台主动调用	签名验证	跨表格引用更新、定时任务

用户操作触发类型 (Type = 0)

触发场景：

用户打开文档页面

用户编辑文档内容

用户执行权限相关操作

其他用户主动发起的操作

验证机制：

工作流程：

Token 特征：

由接入方颁发给用户

在用户浏览器会话中保持

包含用户身份和权限信息

具有过期时间限制

详见签名凭证-Token

验证要点：

✅ 验证 Token 格式和签名

✅ 检查 Token 是否过期

✅ 确认用户身份和权限

✅ 记录访问日志

系统主动触发类型 (Type = 3)

触发场景：

跨表格引用数据更新

定时任务执行

系统维护操作

其他石墨中台主动发起的调用

验证机制：

工作流程：

Signature校验方式示例

Java

  <dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>4.4.0</version>
  </dependency>

为什么要有回调接口？#

回调接口机制详解#

工作原理#

回调接口分类#

回调接口地址#

回调凭证类型#

凭证类型概览#

用户操作触发类型 (Type = 0)#

系统主动触发类型 (Type = 3)#

为什么要有回调接口？

回调接口机制详解

工作原理

回调接口分类

回调接口地址

回调凭证类型

凭证类型概览

用户操作触发类型 (Type = 0)

系统主动触发类型 (Type = 3)