用途:接收并验证 Tally 表单 Webhook,适用于搭建 Tally 表单 Webhook 处理器、调试 Tally-Signature 签名验证、处理 FORM_RESPONSE 表单提交事件,以及从 data.fields 读取表单答案。
主要能力:Tally 使用可选的签名密钥对 Webhook 签名,请求携带 Tally-Signature 头(大小写不敏感),其值为 base64(HMAC-SHA256(signingSecret, rawJsonBody))。该方案没有时间戳机制,也不属于 Standard Webhooks 规范。必须对原始请求体做 HMAC,重新序列化解析后的 JSON 可能改变字节或键顺序导致比对失败。若未配置签名密钥,Tally 发送未签名请求,处理器需自行决定如何处理缺失该头的情况;推荐设置签名密钥并拒绝未签名或无效请求。
事件与载荷:Tally 只有一种 Webhook 事件类型 FORM_RESPONSE,在受访者提交表单时触发,常见用途包括同步提交到 CRM/数据库、发送通知、触发工作流。载荷包含 eventId、eventType、createdAt 以及 data(含 responseId、submissionId、respondentId、formId、formName、fields)。答案位于 data.fields,每项含 key、label、type、value。
使用方式:环境变量 TALLY_SIGNING_SECRET 为每个 Webhook 的密钥(来自表单 Integrations 标签页,可选但推荐)。本地开发可运行 npx hookdeck-cli listen 3000 tally --path /webhooks/tally 启动隧道(无需账号)。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。
限制:Tally Webhook 在所有套餐免费;端点须在 10 秒超时内返回 2XX 状态;失败投递按 5m → 30m → 1h → 6h → 1d 重试,耗时操作应异步执行。建议配合 webhook-handler-patterns 技能处理处理器顺序、幂等性、错误处理与重试逻辑。