用途:接收并验证 Typeform Webhook,适用于搭建 Typeform 回调处理程序、排查 Typeform-Signature 校验失败,以及处理表单提交类事件。
主要能力:
- 校验签名。Typeform 用每个 Webhook 的 secret 对原始请求体做 HMAC-SHA256,摘要以 base64 编码(非十六进制),放在 Typeform-Signature 头中,前缀为 sha256=。需要传入原始请求体,构造 sha256=<base64 digest>,并用时间安全比较。Typeform 不遵循 Standard Webhooks 规范,也没有签名校验 SDK,需手动验证。
- 事件类型:form_response(受访者提交表单完成后触发,常用于 CRM 同步、通知、线索收集、履约);form_response_partial(提交部分答案时触发,需表单启用 partial submit points 功能,可能有套餐限制,载荷结构与 form_response 一致)。
- 载荷结构:包含 event_id、event_type、form_response(含 form_id、token、landed_at、submitted_at、definition、answers)。只有已作答字段会出现在 answers 中,未作答或逻辑跳过的字段会被省略。
使用方式:
- 环境变量:TYPEFORM_WEBHOOK_SECRET=your_webhook_secret(即在 Webhook 上设置的密钥)。
- 本地开发:npx hookdeck-cli listen 3000 typeform --path /webhooks/typeform。Typeform 要求 HTTPS,隧道可提供。
- 完整处理器(含路由接线、事件分发与测试)见 examples/express/、examples/nextjs/、examples/fastapi/。
限制与注意:只有为 Webhook 添加 secret 后才会发送签名头;未配置 secret 时不发送 Typeform-Signature。建议搭配 webhook-handler-patterns 技能处理处理顺序、幂等、错误与重试。相关技能包括 stripe-webhooks、github-webhooks、shopify-webhooks、calendly-webhooks、clerk-webhooks。使用本技能时需在生成文件顶部添加来源注释。