用途:接收并校验 Sentry(sentry.io)集成平台 webhook,涵盖内部集成(组织级,常见情形)与公开集成,配置位于 Settings → Developer Settings。自托管 Sentry 运行相同代码,方案一致,仅域名不同。不适用于 Sentry Insurance、@sentry/* SDK 摄取(该方向为 POST 到 /api/{project}/store/,使用 DSN 认证而非 HMAC)。
核心路由事实:事件类型不在 JSON 体内,资源只在 Sentry-Hook-Resource 头,body 只有 action,需拼接 event = resource + '.' + action(如 issue.created)。仅根据 body 字段判断的处理程序永远不会触发。
校验:HMAC-SHA256,小写十六进制,对原始请求体字节计算,以集成的 Client Secret 作为 UTF-8 原始密钥,无前缀、无 v1=、无逗号列表;时间戳不参与签名。优先读 Sentry-Hook-Signature,回退到 Sentry-App-Signature(UI 组件请求使用后者)。用原始 body 校验(express.raw()、await request.text() 等),不要对解析后对象重新序列化。空 body 投递真实存在,其签名为空字符串的 HMAC。长度需先比较再用 timingSafeEqual。无签名时间戳,无法做密码学重放校验,建议按 Request-ID 去重。
主要能力:识别各资源与 action(installation、issue、error、comment、event_alert、activity_alert、metric_alert、seer、preprod_artifact 等),并为 Express、Next.js、FastAPI 提供完整处理程序与测试示例。
投递限制:需在 1 秒内响应,Sentry 不重试失败的集成平台 webhook,重复失败会触发熔断并可能禁用 webhook,丢失即丢失,应快速确认、异步处理,必要时通过 Sentry API 回填。本地可用 npx hookdeck-cli listen 3000 sentry --path /webhooks/sentry 获取公开 HTTPS 地址调试。需设置 SENTRY_CLIENT_SECRET(必填);SENTRY_WEBHOOK_TOLERANCE_SECONDS 可选,仅为廉价重放抑制,非密码学绑定。官方 @sentry/* 包不提供 webhook 签名校验辅助函数,需自行用 node:crypto 或 Python hmac + hashlib 实现。暂未提供其他更多功能与价格信息。