SuperAPI AI 工具集

Linear Webhooks (Verify, Replay, DLQ)

编程与开发

查看项目

更新于 10-16 07:20

技能介绍

用途:在注册、验证或处理 Linear Webhook 时使用,覆盖签名校验、防重放、幂等与漏发恢复。参考 https://linear.app/developers/webhooks。

签名验证:Linear 对每次投递使用 HMAC-SHA256,头为 Linear-Signature(十六进制摘要)。需以常量时间比较,且必须读取原始 body 字节而非已解析 JSON。Express 可用 app.use("/linear/webhook", express.raw({ type: "application/json" }))。

防重放:body 内含 webhookTimestamp(Unix 毫秒),超过 5 分钟的旧事件应拒绝:if (Math.abs(Date.now() - body.webhookTimestamp) > 5 * 60_000) reject();

幂等:Linear 可能重复投递。用 delivery.id(唯一)而非 data.id 去重,可将已见 delivery.id 存入 Redis 并设 7 天 TTL。重试投递去重由 lib/webhooks.mjs 中的 DeliveryDeduper 在进程内处理,以 Linear-Delivery 为键,受大小和 TTL 约束。

资源与动作:资源类型含 Issue、IssueLabel、Comment、Cycle、Project、ProjectUpdate、Initiative、InitiativeUpdate、Customer、CustomerNeed、Reaction、Attachment、Document;动作类型为 create | update | remove,部分资源支持更多。建议按需订阅以减少事件量。body 结构含 action、actor、createdAt、data、type、url、webhookTimestamp、webhookId、delivery.id。

读取:不要信任 payload 状态,Linear 可能乱序发送,收到 Issue update 后应通过 GraphQL 按 id 重新获取权威状态。

恢复漏发:该插件刻意不提供死信队列,改用对账:/linear:sync reconcile --dry-run 与 /linear:sync reconcile --apply。理由是 DLQ 只能修复已到达但失败的事件,无法修复从未发送、跨越重试窗口的故障或手工修改造成的漂移,而对账可覆盖这些且无需 webhook 即可测试。早前版本提到的 lib/webhook-dlq.ts 与 /linear:webhook replay 均不存在。

本地测试:用 ngrok http 3000 暴露本地接收端并注册该 URL;可用 /linear:sync event --file <path> 捕获并重放单个投递以走验证与规范化流程。

安全检查清单:仅 HTTPS;在任何超出原始读取的解析前验证签名;5 分钟时间窗;delivery.id 幂等;通过 GraphQL 重取权威状态;有界重试的 DLQ;每年轮换 webhook 密钥。