Meegle 插件监听事件:去重与可靠接入验证
结论与验证范围
官方协议支持按事件唯一标识去重。 本方案使用飞书项目(Meegle)插件的「监听事件」,去重字段是请求体中的 data.idempotent_key,不是 event_id、log_id 或自动化 Webhook 的 header.uuid。[S1][S3]
本次通过浏览器读取官方文档正文,完成协议层可行性核对;没有实际注册插件、接收真实回调、制造超时或验证服务端实现。下面严格区分平台合同、拟定设计与待联调事项。
官方协议事实
1. 公网 POST、1 秒响应、有限重试
官方《监听事件》要求回调地址公网可访问,事件通过 HTTP/HTTPS POST 发送;插件配置相关事件并发布版本、在空间安装后生效。[S1]
原文:
你在接收到飞书项目的请求后,需要在1000ms内返回状态码为200的响应。
为保证用户可以正确接收到监听事件,当发送失败后,会进行4次重试(重试间隔为立即重试,1分钟,2分钟,7分钟)。重试4次仍然发送失败,则不会继续重试。
这里的间隔按官方原文记录,不换算成绝对重试时刻。官方建议将耗时业务异步处理。我们的入口采用 HTTPS;公网入口可通过网关转发到内部调度中心,不需要暴露整个调度服务。[S1;后两句为项目设计]
2. 去重键与乱序
官方原文:
同一事件可能多次发送,开发者可以通过请求体body中的事件唯一标识("idempotent_key")自行过滤。
通用结构中的关键字段(省略其他字段):
{
"log_id": "...",
"request_time": 1730184005453,
"signature": "...",
"source": "normal",
"source_plugin_id": "...",
"data": {
"event_type": 3001,
"idempotent_key": "..."
}
}
官方字段解释明确 data.idempotent_key 是「事件的唯一标识」。因此使用它过滤同一事件的重复推送有直接文档依据,而不是假设 HTTP 请求体或请求时间在每次重试中不变。[S1]
事件无序发送。文档建议参考 request_time,并将它解释为事件发送时间、通常近似事件发生时间。因此不能把它当作严格的卡片版本号,也不能认为接收去重就解决了旧状态晚到的问题。[S1;最后一句为设计推论]
文档未明确唯一标识的全局唯一范围、保留期、人工重放是否沿用原键、重试时 request_time 是否变化。落地时需联调,不承诺任何场景的 exactly-once。
3. 验签
配置回调 token 后,官方验签规则是:[S1][S2]
expected_signature = hex(SHA256(plugin_id + request_time + callback_token))
按文档顺序直接拼接字符串,不是 HMAC,也不是 GitHub 或普通飞书事件的签名规则。回调 token 虽为平台可选配置,本方案要求配置,并由可信接入配置绑定插件身份后进行校验。
该公式不包含 data 全量内容,不能宣传为完整载荷的密码学防篡改保证。需要 HTTPS、保密 token、入口防护;事件来源鉴别也不能代替操作人审批权核对。防重放时间窗口需结合实际重试报文验证,不能贸然按首次事件时间设置过短窗口。[S2;后两句为项目安全要求]
4. 不要混用自动化 Webhook
产品手册《Webhook 使用》描述的是在「自动化规则」中添加 Webhook 操作的另一套机制:[S3]
- 幂等串为 JSON 请求体中的
header.uuid,不是 HTTP header。 - 超时为 6 秒,最多重试 3 次。
- 该页将 1xx / 2xx 描述为成功响应。
这些规则不适用于本方案采用的插件监听事件。插件监听事件采用 data.idempotent_key、1000ms、HTTP 200、失败后 4 次重试。[S1]
5. Lark 是另一条接入线路
Lark 官方 Node SDK 文档支持用 WSClient 建立 WebSocket 长连接接收机器人消息事件,无需对外提供公网 IP 或域名;该连接与 Meegle 插件监听事件的公网回调分开配置。SDK 文档同时说明长连接消费仍有自己的超时重推机制,不能将其理解为无需幂等。[S4]
本次只确认 Lark 长连接接入能力,不把 Lark 消息的去重字段或超时规则套用到 Meegle。
拟定的调度中心接收设计(不是平台已提供能力)
- 校验入口:HTTPS 接收,绑定可信插件配置,校验结构和签名;非法请求不触发任务。缺少必要去重键的事件隔离并告警,不静默绕过去重。
- 持久化接收:以「本地接入配置 + 租户/空间 +
data.idempotent_key」建立持久化唯一约束。命名空间按最终报文字段及接入配置确定,不把来源插件字段直接当成接收插件身份。唯一写入和后续可恢复处理安排必须可靠衔接,例如事务事件表加扫描/outbox;不能先标记已接收,再依赖可能丢失的内存派工。 - 快速应答:验签并可靠记录后,1000ms 内返回 HTTP 200。相同键已经可靠接收的重复请求直接应答,不重复创建任务。未能可靠保存时不返回成功,允许上游有限重试。
- 异步消费:记录待处理、处理中、成功、失败等状态;崩溃恢复后继续处理未完成事件。HTTP 200 只代表可靠接收,不代表 Agent 已完成。
- 副作用幂等:任务创建、卡片流转、通知和计数还需要业务动作唯一键/条件更新。平台重推、内部工作进程重试、两个不同事件指向同一动作,都不能重复派工或计数。外部写入成功但本地确认失败时,先核对执行结果,不能盲目重做。
- 乱序与补偿:动作前核对当前卡片状态和本地流程版本/前置条件,拒绝旧事件倒退流程;时间戳仅辅助判断。处理失败由内部重试、隔离、告警和对账补偿承接,不依赖平台无限重试。
- 区分重推和反馈循环:Agent 回写产生的新事件可能具有新去重键;需要结合本地动作记录及事件来源识别反馈,不能只靠事件键去重,也不能一律丢弃所有 Open API 来源事件。
待联调验证清单
- 同一事件被故意超时/非 200 触发重推时,
data.idempotent_key保持事件身份;观察request_time、签名及实际重试节奏。 - 多个工作项/节点/状态事件是否都具备预期的唯一标识和租户、空间、操作人字段;确认不同安装/订阅及人工重放的标识范围。
- 多进程同时接收同一事件,只落一条有效接收记录、创建一个业务任务。
- 保存后应答前崩溃、应答后消费前崩溃、业务执行后确认前崩溃,均可恢复且不重复副作用。
- 相同卡片事件乱序、Agent 自身回写、平台重试耗尽,以及敏感字段脱敏与审计。
- 入口在预期峰值下完成验签、持久化和应答的端到端耗时满足 1000ms;日志排队或 Agent 启动不得阻塞应答。
- 回调 token 轮换、防重放窗口、网络入口安全,以及未通过校验的请求隔离策略。
这些是验收条件,不是已完成的测试结果。
官方来源
- S1 监听事件 — 飞书项目开发者手册:配置流程、重点说明、稳定性说明、事件结构。
- S2 兼容性说明与验签说明 — 飞书项目开发者手册:验签公式、示例代码与公网回调要求。
- S3 Webhook 使用 — 飞书项目产品手册:自动化规则 Webhook 的格式、成功标准与重试机制,仅用于辨别不同协议。
- S4 Lark 官方 Node SDK:Subscribing to Events Using Long Connection Mode:
WSClient、连接模式和注意事项;其引用的官方长连接文档。