用途:帮助搭建 Quoter Webhook 处理程序,调试 MD5 哈希校验失败,理解 Quote、Person、Payment 对象类型及创建与更新的区别,并解析 application/x-www-form-urlencoded 的 hash、timestamp、data 载荷。
主要能力:Quoter 不使用 HMAC-SHA256,也不是 Standard Webhooks,而是旧式 MD5 共享密钥哈希,且哈希密钥可选,甚至可完全不校验。签名是名为 hash 的表单字段,不是 HTTP 头。校验方式为计算 md5(HASH_KEY + timestamp + data) 并与 hash 比较;data 必须按原样字符串参与哈希,不能重新序列化解析后的 JSON。timestamp 为 GMT UNIX 秒,可据此拒绝过期请求(示例为 300 秒内)。
事件模型:Quoter 没有点分事件名,而是在 Settings → Integrations 的 Applies To 中订阅对象类型,该类型对象创建或更新时触发。对象类型不包含在载荷或 HTTP 头中,因此需为每种对象类型配置不同目标 URL,例如 https://your-app.com/webhooks/quoter?object=quote,并在处理器中据此分发。同一对象创建与更新都会触发,应按记录 id 做幂等处理。
使用方式:设置环境变量 QUOTER_HASH_KEY;本地开发可用 npx hookdeck-cli listen 3000 quoter --path /webhooks/quoter,将打印的 URL 追加 ?object=quote、?object=person 或 ?object=payment 后填入 Quoter 集成目标 URL。示例目录包括 examples/express/、examples/nextjs/、examples/fastapi/。
限制与安全:MD5 已被密码学攻破,应视为低保障校验,并配合网络层控制(IP 允许列表、URL 路径共享密钥或前置 Hookdeck)。务必在 Quoter 中设置哈希密钥,否则任何知道端点 URL 的人都能伪造请求。生成文件时按要求添加注释:// Generated with: quoter-webhooks skill 与 // https://github.com/hookdeck/webhook-skills。建议同时安装 webhook-handler-patterns 技能以处理处理器顺序、幂等、错误处理与重试逻辑。