整体概述

当用户在石墨文档中创建评论、@ 人、更新文件内容、添加协作者时，石墨会通过 POST {endpoint_url}/events 把事件推送到你的应用。如果你的应用需要感知这些事件，来触发后续其他的业务流程，可以通过处理回调事件的方式来实现这个目标。

如果你的应用没有订阅石墨文档事件来触发后续业务流程处理的场景，那么可以跳过此文档。

一、如何快速对接事件推送

先在控制台或更新应用回调地址把 endpointUrl 设好，所有事件统一推送到 {endpointUrl}/events。

实现一个 POST /events 路由：按 X-Shimo-Sdk-Event 头分发，不管业务处理成败都尽量返回 200 {}，避免触发 10009 / 10010 错误。

处理逻辑必须幂等：石墨在网络抖动或你的应用返回非 200 时会重试，重复事件可能到达多次。

联调阶段同时监听 System 事件下的「回调请求错误」，可以在分钟级感知到自己接口出现的失败。

二、事件总览

下表是当前所有可推送事件。X-Shimo-Sdk-Event 头取 kind（必要时附带 type）作为路由依据，载荷对象是该事件携带的业务字段所在的 JSON key。

X-Shimo-Sdk-Event	kind	type	action 取值	载荷对象	触发时机
`Comment`	`Comment`	`comment`	`create` / `update` / `delete` / `resolve`	`comment`	用户增加、修改、删除或结束评论
`Comment`	`Comment`	`discussion`	`create` 等	`discussion`	用户发送讨论消息
`MentionAt`	`MentionAt`	`mention_at`	`create`	`comment.userIds`	用户在评论中 @ 了人
`DateMention`	`DateMention`	—	`create` / `update` / `delete`	提醒规则	用户插入、修改、删除日期提醒规则（石墨不负责到点提醒）
`FileContent`	`FileContent`	—	`update`	`fileContent`	文档内容被修改并保存成功
`CollaboratorChanged`	`CollaboratorChanged`	—	`enter` / `leave`	`collaboratorChanged`	用户进入或离开协同
`Revision`	`Revision`	—	`create` / `update` / `delete`	`revision`	用户创建、修改、删除版本
`System`	`System`	`callback_request_error` 等	—	`request` / `response`	SDK 系统级事件，当前以「回调请求错误」为主

三、整体推送时序

四、请求与响应规范

请求地址

POST {endpoint_url}/events

endpoint_url 来自应用注册时配置的回调前缀，可通过更新应用回调地址修改。

Header 参数

名称	必填	类型	说明
`X-Shimo-Sdk-Event`	是	string	路由依据，取值见上表
`X-Shimo-Token`	视事件而定	string	石墨持有当前用户 Token 时传入，用于你的应用对本次请求鉴权
`X-Shimo-Credential-Type`	视事件而定	string	石墨无法提供用户 Token 时填写，参考 Token 与回调鉴权
`X-Shimo-Signature`	视事件而定	string	石墨用应用 `appId / appSecret` 主动签发的 JWT，用于无 Token 时的请求来源校验

Response

HTTP Code：200。任何非 200 都会被识别为失败，并触发 10009 / 10010。

Body：空 JSON {} 即可，石墨不读取响应体。

超时：默认 5 秒，超时按失败处理。

五、凭证类型

不同事件触发源不同，到达你的应用时携带的凭证组合也不同。务必按凭证类型分别校验，不要假设 X-Shimo-Token 永远存在。

事件	触发源	`X-Shimo-Token`	`X-Shimo-Credential-Type`	`X-Shimo-Signature`	校验建议
`Comment` / `MentionAt` / `Revision` / `DateMention`	用户主动操作	有	通常省略	通常省略	用 Token 还原用户后再判断业务权限
`FileContent` / `CollaboratorChanged`	编辑器内核 + 协同服务	无	`3`	有	校验 `X-Shimo-Signature` 来源；用户用 `userId` 字段定位
`System` 下的回调错误	石墨服务端	无	`3`	有	同上

六、重试与去重策略

重试节奏：失败后石墨在分钟级内做 2~3 次指数退避重试；超过重试次数后写入推送失败日志，并通过 System 事件二次通知。

去重键：石墨不保证事件只送达一次。建议在你的应用侧用业务幂等键去重；下表给出推荐键：

事件	推荐幂等键	备注
`Comment`	`comment.guid + action`	同一评论可能经历 `create → update → resolve`
`MentionAt`	`comment.guid + userIds 排序后`	一条评论 @ 多人时，避免重复通知
`DateMention`	`fileId + ruleId + action`	规则 ID 在事件 body 内提供
`FileContent`	`fileId + fileContent.version`	版本号单调递增，作幂等最稳
`CollaboratorChanged`	`fileId + userId + clientId + action + timestamp`	多端登录时同用户的不同实例
`Revision`	`fileId + revision.revisionId + action`	—
`System.callback_request_error`	`appId + request.url + timestamp`	同一接口可能短时间多次失败

快入慢处理：5 秒内尽快返回 200，把 IM 推送、邮件、AI 处理等耗时业务放进消息队列异步消费。

乱序保护：事件可能乱序到达（尤其 enter 在 leave 后）。对计数器、在线集合一类的状态，应该用 timestamp 做单调比较，过期事件丢弃。

七、排查清单

现象	可能原因	修复方向
控制台日志频繁出现 `10009 / 10010`	你的应用返回非 200 / 3xx / 抛 5xx	检查 `/events` 路由是否被前置中间件（鉴权、CSRF）拦截；返回体改成 `200 {}`
同一事件被重复处理	你的应用偶发返回 5xx 触发石墨重试	加幂等键 + 入队
收不到 `FileContent` 事件	endpoint 没配；高频编辑被合并 / 限流；防火墙拦截	看 `System.callback_request_error`；网关侧确认石墨出口 IP
`MentionAt` 触发但 IM 没推送	业务侧把 `Comment` 也当作 @ 触发，去重逻辑误删	用 `comment.guid + userIds` 做幂等，按 `MentionAt` 为唯一触发
`DateMention` 创建后没有按时提醒	误以为石墨负责到点	由你的应用维护 schedule，到点自行下发
`X-Shimo-Token` 缺失返回 401	事件来源是石墨主动签发，没有用户 Token	走 `X-Shimo-Credential-Type=3 + X-Shimo-Signature` 通道，不要强校验 Token
签名校验失败	时钟漂移 / appSecret 不对 / 缓存了旧密钥	同步 NTP；用签名工具对照；轮换密钥后清缓存
协同人头像列表偶发漏人	仅按 `userId` 维护在线集合，多端登录时被误删	按 `(userId, clientId)` 二元组维护，全部 `clientId` 离开才视为下线

八、公共字段

绝大多数事件都包含下面这组公共字段，载荷对象单独列在分章里。

字段	类型	必填	含义
`kind`	string	是	事件大类，对应 `X-Shimo-Sdk-Event`
`type`	string	否	子类型，例如 `comment` / `discussion` / `mention_at`
`action`	string	视事件	业务动作，例如 `create` / `update` / `delete` / `enter` / `leave`
`fileId`	string	是	你的应用的文件 ID
`userId`	string	是	你的应用的用户 ID；触发此事件的用户
`timestamp`	integer	是	事件产生时间，毫秒级时间戳

九、事件 → 业务动作映射

这张表给出每个事件最常见的业务侧处理，可以作为接入清单。

事件	业务侧典型动作	是否建议落库	是否要触发用户通知
`Comment`	同步评论到业务消息中心 / 审批流；维护未读数	是	视评论是否提及用户
`MentionAt`	给被 @ 用户发 IM / 站内信 / 待办	是	是（唯一触发点）
`Revision`	更新版本列表入口；写审计	是	仅创建时（可选）
`FileContent`	刷新业务文件「最近修改时间 / 最近编辑人」	视频率	否（高频，不要触达用户）
`CollaboratorChanged`	维护「正在编辑的人」缓存；做在线人头像	视频率，可只入缓存	否
`DateMention`	同步规则到 schedule；到点由自家定时任务下发	是	到点时由自家系统发
`System.callback_request_error`	接入企业 IM 告警；触发自动 oncall	是	是（运维侧）

十、事件详解

更详细的事件内容见本章节子目录。

评论 Comment

触发时机：用户在文档中增加、修改、结束（resolve）或删除一条评论。X-Shimo-Sdk-Event: Comment，凭证：用户 Token。

字段	类型	必填	说明
`comment.guid`	string	是	评论 ID
`comment.content`	string	是	评论文本内容
`comment.userIds`	string[]	是	评论中被 @ 的用户；同样的信息会通过 `MentionAt` 再单独推送一次
`comment.selectionGuid`	string	是	划词高亮区域 ID
`comment.selectionContent`	string	是	选中的文字内容

示例：

{
  "kind": "Comment",
  "type": "comment",
  "action": "create",
  "fileId": "doc_123",
  "userId": "user_42",
  "timestamp": 1717200000000,
  "comment": {
    "guid": "cmt_abc",
    "content": "这里要不要补一句免责声明？",
    "userIds": ["user_7"],
    "selectionGuid": "sel_xyz",
    "selectionContent": "本服务不构成投资建议"
  }
}

处理建议：评论事件经常和 MentionAt 成对出现。如果你的业务系统已经监听 MentionAt 做 @ 通知，建议在 Comment 处理器里跳过 userIds，避免一条 @ 评论触发两次推送。

讨论 Discussion

触发时机：用户发送讨论消息。Header 同 Comment，type: discussion，载荷对象 discussion。

字段	类型	必填	说明
`discussion.id`	string	是	讨论消息 ID
`discussion.unixus`	integer	是	微秒级时间戳
`discussion.content`	string	是	讨论文本
`discussion.positionId`	string	是	预留字段，目前无用，请保留透传

提及 MentionAt

触发时机：用户在评论、讨论或正文中 @ 了人。X-Shimo-Sdk-Event: MentionAt，type: mention_at，action: create，凭证：用户 Token。

载荷字段同「评论」，关键是 comment.userIds。处理建议：把这条事件作为 IM / 站内信通知的唯一触发点，幂等键 comment.guid + 排序后的 userIds。

示例：

{
  "kind": "MentionAt",
  "type": "mention_at",
  "action": "create",
  "fileId": "doc_123",
  "userId": "user_42",
  "timestamp": 1717200000000,
  "comment": {
    "guid": "cmt_abc",
    "content": "@张三 看下这段表述",
    "userIds": ["user_7"],
    "selectionGuid": "sel_xyz",
    "selectionContent": "..."
  }
}

日期提醒 DateMention

触发时机：用户在文档中插入、修改、删除「日期 + 提醒人」规则时立即推送。X-Shimo-Sdk-Event: DateMention，action: create / update / delete，凭证：用户 Token。

说明

石墨只在规则发生变更时通知，不会在目标时间到达时再发一次。如果业务需要「到点提醒」，需要由你的应用自行落库 + 起定时任务。

处理建议：把日期提醒规则同步到你的应用的 schedule 表里，按 fileId + ruleId 做主键；删除事件到来时也同步清理。

文件内容更新 FileContent

触发时机：文档内容被用户修改并被石墨服务器处理成功后推送。X-Shimo-Sdk-Event: FileContent，action: update。这条事件大概率以 X-Shimo-Credential-Type=3 + X-Shimo-Signature 的方式到达。

字段	类型	必填	说明
`fileContent.version`	integer	是	此次更新产生的新版本号

示例：

{
  "kind": "FileContent",
  "type": "FileContent",
  "action": "update",
  "fileId": "doc_123",
  "userId": "user_42",
  "timestamp": 1717200000000,
  "fileContent": { "version": 314 }
}

处理建议：这是更新业务侧「最近修改时间 / 最近编辑人」最准确的来源。高频写入文档时事件会被合并和限流，不要把它当成实时光标级别的同步；用 version 做幂等键最稳。

协作者协同状态变化 CollaboratorChanged

触发时机：协同列表中的某个用户进入或离开。X-Shimo-Sdk-Event: CollaboratorChanged，action: enter | leave，凭证多为 Credential-Type=3 + Signature。

字段	类型	必填	说明
`collaboratorChanged.clientId`	string	是	协作客户端实例 ID；同一用户多端登录时每端的 `clientId` 不同

处理建议：用于做「正在编辑的人头像列表」时，按 (fileId, userId, clientId) 维护在线集合，不要直接按 userId 增删——一个用户多端时 leave 会先于 enter 到来，按 userId 删除会误下线。

版本 Revision

触发时机：用户创建、修改、删除文档版本。X-Shimo-Sdk-Event: Revision，action: create | update | delete，凭证：用户 Token。

字段	类型	必填	说明
`revision.revisionId`	integer	是	版本号
`revision.title`	string	是	版本标题
`revision.label`	string	是	版本标签
`revision.docHistoryId`	string	是	历史快照 ID

处理建议：用来同步业务侧「版本列表」入口或追加审计记录，不要当成普通编辑事件，编辑请订阅 FileContent。

系统事件 System

X-Shimo-Sdk-Event: System，目前以「回调请求错误」（callback_request_error）为主要子类型，仍为实验性事件，未来字段可能变化。凭证：Credential-Type=3 + Signature。

回调请求错误的载荷关键字段：

字段	类型	必填	说明
`kind`	string	是	固定为系统事件标识
`type`	string	是	错误类型，例如 `callback_request_error`
`appId`	string	是	应用 ID
`timestamp`	integer	是	毫秒级时间戳
`request.url`	string	是	石墨实际请求的 URL
`request.headers`	object	是	含 `X-Shimo-Token` / `X-Shimo-Signature`
`request.body`	string	是	请求体（字符串化）
`response.status`	integer	是	你的应用返回的 HTTP 状态
`response.headers`	object	是	你的应用返回的响应头
`response.body`	string	是	你的应用返回的响应体
`errorMessage`	string	是	石墨侧补充的错误说明

处理建议：把这条事件落库的同时，告警 request.url + response.status + errorMessage，能在分钟级定位到具体回调接口故障。注意：石墨明确说此事件未覆盖所有失败场景，所以你的应用仍应在自己接口侧做监控。

十一、实战代码骨架

下面是接入 /events 的最小骨架（伪代码，未做异常处理）：

app.post('/events', async (req, res) => {
  const eventName = req.headers['x-shimo-sdk-event']
  const credType = req.headers['x-shimo-credential-type']
  const token = req.headers['x-shimo-token']
  const signature = req.headers['x-shimo-signature']

  // 1. 来源校验：Token 优先，否则走签名
  let userContext
  if (token) {
    userContext = await resolveUserByToken(token)
  } else if (credType === '3' && verifySignature(signature)) {
    userContext = { system: true }
  } else {
    return res.status(401).end()
  }

  // 2. 幂等去重（按事件 → 幂等键映射）
  const idempotencyKey = buildIdempotencyKey(eventName, req.body)
  if (await seen(idempotencyKey)) return res.json({})
  await markSeen(idempotencyKey, ttlSeconds = 7 * 86400)

  // 3. 快入慢处理：入队，业务逻辑异步消费
  await eventQueue.push({ eventName, body: req.body, userContext })

  // 4. 始终返回 200，避免触发 10009 / 10010
  res.json({})
})

异步消费侧，按事件分发：

async function handleEvent({ eventName, body }) {
  switch (eventName) {
    case 'MentionAt': return notifyMentionedUsers(body.comment)
    case 'Comment':   return syncCommentToInbox(body.comment, body.action)
    case 'FileContent': return updateDocLastModified(body.fileId, body.fileContent.version)
    case 'CollaboratorChanged': return updatePresence(body)
    case 'Revision':  return appendAuditLog(body.revision, body.action)
    case 'DateMention': return upsertSchedule(body)
    case 'System':    return alertOps(body)
  }
}

一、如何快速对接事件推送#

二、事件总览#

三、整体推送时序#

四、请求与响应规范#

五、凭证类型#

六、重试与去重策略#

七、排查清单#

八、公共字段#

九、事件 → 业务动作映射#

十、事件详解#

评论 Comment#

讨论 Discussion#

提及 MentionAt#

日期提醒 DateMention#

文件内容更新 FileContent#

协作者协同状态变化 CollaboratorChanged#

版本 Revision#

系统事件 System#

十一、实战代码骨架#

一、如何快速对接事件推送

二、事件总览

三、整体推送时序

四、请求与响应规范

五、凭证类型

六、重试与去重策略

七、排查清单

八、公共字段

九、事件 → 业务动作映射

十、事件详解

评论 Comment

讨论 Discussion

提及 MentionAt

日期提醒 DateMention

文件内容更新 FileContent

协作者协同状态变化 CollaboratorChanged

版本 Revision

系统事件 System

十一、实战代码骨架