SuperAPI AI 工具集

linear-webhooks-events

通用与其它

查看项目

更新于 10-15 23:27

技能介绍

用途:为 Linear Webhook 构建安全的入站处理链路,确保请求真实性可验证、确认及时、下游处理可重放。

主要能力:

  • 签名验证:Linear-Signature 是对精确原始请求体的 HMAC-SHA256 十六进制值,配合 Linear-Delivery(投递 UUID)与 Linear-Timestamp(epoch 毫秒)。
  • 快速确认:端点需为公开 HTTPS,并在 5 秒内返回 HTTP 200;失败后按 1 分钟、1 小时、6 小时重试,最多 3 次。
  • 去重与幂等:按 Linear-Delivery 去重,结合 action、type、实体 ID、updatedFrom、organization、webhook ID 等做幂等处理。
  • 排队与对账:验证后先入队再处理,限制重试并设死信处理;定期做基于游标的对账。
  • 官方 SDK:提供 LinearWebhookClient,含原始体签名验证与框架处理器。

使用方式:选择明确的资源类型与团队/全部公开团队范围并确定负责人;在 JSON 中间件之前捕获精确原始字节;用配置的签名密钥验证 HMAC-SHA256;拒绝无效或过期/重放请求;去重后入队并在 5 秒内返回 200;按上述字段幂等地处理事件;测试创建/更新/删除、重复、延迟、应用被撤销、密钥轮换等场景。

认证:个人 API 密钥仅用于所有者控制的脚本(Authorization: <API_KEY>),用户委托应用用 OAuth PKCE(Authorization: Bearer <ACCESS_TOKEN>),批准自动化可用客户端凭证授予。凭据存于服务端密钥管理器。

适用场景:接收 Linear 的 issue、项目、周期等事件并进行可靠的异步处理。

限制:只有工作区管理员或具备 admin 范围的 OAuth 应用可创建或读取 Webhook;不要假设 Linear 会超出文档计划重试;创建、轮换或撤销凭据及对工作区数据的变更均需责任人明确批准;诊断默认只读。缺失的实现细节与具体代码示例暂未提供。