SuperAPI AI 工具集

sanity-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证 Sanity 的 GROQ 驱动 Webhook,适用于搭建 Sanity Webhook 处理器、排查 sanity-webhook-signature 校验失败、在文档变更时触发缓存重验证或搜索重建索引,以及处理 Content Lake 的文档创建、更新、删除事件。

主要能力:Sanity 没有固定的事件类型字符串,Webhook 在 sanity.io/manage 配置,通过 GROQ filter 决定哪些文档变更触发,通过 GROQ projection 塑造 JSON 请求体;projection 为空时载荷为变更后的完整文档,始终包含 _id、_type、_rev。处理器按文档 _type(及投影字段)分发,而非按提供方定义的事件名。Webhook 在 Content Lake 的创建/更新/删除时触发,默认忽略草稿与版本文档。

验证方式:Sanity 使用官方 @sanity/webhook 包签名(v4 需 Node 18+)。sanity-webhook-signature 头为 Stripe 风格 t=<毫秒时间戳>,v1=<sig>,是对 ${timestamp}.${rawBody} 的 HMAC-SHA256,base64url 编码且无填充。必须传入原始请求体,不要先 JSON.parse。isValidSignature 在 v4+ 为异步,返回布尔值,签名错误不抛异常。Python 无官方包,FastAPI 需手动解析 t/v1、重算 base64url HMAC 并做时序安全比较。

使用方式:设置环境变量 SANITY_WEBHOOK_SECRET;完整处理器、路由接线、事件分发与测试见 examples/express/、examples/nextjs/、examples/fastapi/。本地开发可用 npx hookdeck-cli listen 3000 sanity --path /webhooks/sanity 启动隧道。

限制:投递为至少一次,1 个并发请求、30 秒间隔重试 2 次、30 秒超时,不应把 Webhook 作为唯一事实来源,需用 idempotency-key 请求头去重。建议配合 webhook-handler-patterns 技能处理处理器顺序、幂等、错误处理与重试逻辑。