SuperAPI AI 工具集

knock-webhooks

测试与质量

查看项目

更新于 10-15 22:14

技能介绍

用途:该技能用于搭建 Knock 出站 Webhook 处理器,验证 x-knock-signature 签名,处理通知消息生命周期事件(sent、delivered、bounced、read、link_clicked 等),以及响应 Knock 资源变更(workflow.committed、translation.committed 等)。也适用于将 Stripe 风格验证器移植到 Knock 时排查静默失败问题。

主要能力:Knock 使用 HMAC-SHA256(base64)对每个 Webhook 签名,请求头为 x-knock-signature: t=<timestamp_ms>,s=<base64_signature>,签名串为 ${timestamp_ms}.${raw_body}。时间戳为毫秒而非秒,这是与 Stripe 的明确差异。官方 SDK(@knocklabs/node、knockapi)不提供入站验证方法,需用标准库自行验证。技能提供 verifyKnockSignature 函数示例,包含时间容差校验与 timingSafeEqual 比较,并附 Express、Next.js、FastAPI 完整处理器示例。

使用方式:设置环境变量 KNOCK_WEBHOOK_SECRET(每个端点独立的签名密钥,来自 Knock 控制台 Webhook 详情页,非账户 API Key)。本地开发可运行 npx hookdeck-cli listen 3000 knock --path /webhooks/knock 启动隧道,将打印的 Hookdeck URL 作为 Knock 控制台中的目标地址。

适用场景:需要处理 Knock 通知事件、调试签名验证失败、或构建幂等 Webhook 处理逻辑时。Knock 对非 2xx 响应会在数小时内重试若干次(不重试 301–303 与 400–405,429 遵循 Retry-After),同一事件可能重复到达;文档载荷无事件级 id,建议用 type、data.id 与 created_at 构建幂等键。

限制:资料未提供收费、价格、平台支持范围等信息;完整事件参考(27 个事件)需查阅 Knock 官方文档。