如何将标准 Webhook 连接到 Shopify Flow
将标准 Webhook 连接到 Shopify Flow，并对每次请求进行 HMAC 签名验证，确保只有可信事件才会触发您的工作流程。
Standard Webhook 是一项用于对 Webhook 进行签名的开放规范，已被 OpenAI、Supabase Auth Hooks 以及越来越多的服务所采用。 一个预设即可覆盖所有这些场景。Workflow Webhooks 将该调用转换为 Shopify Flow 触发器，从而使您的商店能够对此做出响应：标记客户、添加订单备注、发送内部邮件、更新元字段 - - 任何 Shopify Flow 能做到的操作。
本指南详细介绍了整个流程 - - Standard Webhook 发送请求，Workflow Webhooks 接收并验证，Shopify Flow 执行操作 - - 每个请求都会对 Standard Webhook 的 HMAC 签名进行验证，因此只有 Standard Webhook 才能启动您的工作流程。
你可以制作什么
- 获取一个 OpenAI Webhook（一个已完成的批处理任务或已完成的响应），并让 Shopify Flow 根据该结果在您的商店中采取相应操作。
- 响应 Supabase Auth Hook，这样当用户在您的应用中注册时，系统会为匹配的 Shopify 客户添加标签。
- 无需配置自定义签名，即可接收来自任何遵循 standardwebhooks.com 规范的服务的请求。
典型事件包括：发送服务所定义的任何事件。
该预设还会验证来自 OpenAI 和 Supabase Auth Hooks 的 Webhook。
开始之前
- Workflow Webhooks 已安装在您的 Shopify 商店中。
- Shopify Flow 已安装，该应用可从Shopify应用商店免费下载。
- 一个具有创建 Webhook 权限的 Standard Webhook 账户。
步骤 1 - 在 Workflow Webhooks 上创建 Webhook
- 打开 Workflow Webhooks -> Webhook -> 创建 Webhook，并为其命名一个在 Shopify Flow 中能认出的名称，例如
Standard Webhooks events。 - 在**“身份验证**”下，选择 HMAC。
- 在**“签名提供程序**”下，选择**“标准 Webhook”**。该应用会自动为您填入头部、算法、签名负载和重放窗口 - - 无需进行其他配置。
- 暂时将“密钥”字段留空，然后点击“保存”。复制页面上显示的 Webhook URL。
有关其他身份验证模式，请参阅 身份验证；有关如何选择哪些字段会传输到 Shopify Flow，请参阅 负载映射和流变量。
步骤 2 - 在“标准 Webhook”中添加端点
在发送服务中将该 URL 添加为端点，然后复制系统显示的签名密钥（该密钥以 whsec_ 开头）。
如何查找您的标准 Webhook 签名密钥
以 whsec_ 开头的签名密钥。请将其完整粘贴；如果显示为 v1,whsec_...（Supabase），请省略开头的“v1,”。
Standard Webhook 关于 Webhook 签名的官方文档 中，提供了您账户的具体说明文字和截图。
将该密钥粘贴到 Workflow Webhooks 页面中 Webhook 的**“Secret**”字段中，然后保存。从那时起，每条标准 Webhook 的消息在到达 Shopify Flow 之前都会经过验证。
此处检查的内容
| 什么 | 值 |
|---|---|
| 签名页眉 | webhook-signature |
| 签名的位置 | 前缀v1,之后的标头值 |
| 签署了什么 | {header:webhook-id}.{timestamp}.{body} |
| 签名 | HMAC-SHA256，Base64编码 |
| 时间戳 | webhook-timestamp 头文件，以 Unix 秒为单位 |
| 回放保护 | 签名时间戳与当前时间相差超过5分钟的请求将被拒绝 |
| 秘密 | 使用前需先进行Base64解码。解码前会去除开头的whsec_。请完全按照发件人显示的内容粘贴 |
在已签名的负载中，{body} 就是原始请求正文（按字节逐字节复制），{timestamp} 是上文提到的时间戳，而 {header:webhook-id} 则是 webhook-id 的请求头。
如果请求未通过上述任何一项检查，则该请求将被以401状态拒绝，记录在历史与故障排除中，并且永远不会启动工作流程。
步骤 3 - 构建Shopify Flow工作流程
- 在 Shopify Flow 中，创建一个工作流程，并选择“Workflow Webhooks”触发器。
- 点击**“记录事件**”，然后通过“标准 Webhook”发送一个测试事件（或使用Workflow Webhooks 中的**“发送测试”功能**），以便 Shopify Flow 学习您的数据结构。
- 您拥有的每个 Webhook 都会触发同一个 Shopify Flow 触发器，因此请针对 Webhook ID 添加第一个条件，以确保此工作流程仅适用于标准 Webhook。该 ID 显示在 Webhook 页面上。
- 添加操作 - - 标记客户、添加备注、发送内部邮件、更新元字段。
第 4 步 - - 进行端到端测试
在“标准 Webhook”中触发一个真实事件。在 Workflow Webhooks -> 历史记录 中，您应该能看到状态为“成功”的调用记录。如果签名有误，您会看到一条状态为“失败”的记录并附有具体原因；验证已签名的 Webhook 介绍了签名测试工具，该工具会精确显示哪个步骤失败了。
签名不匹配
按以下顺序：密钥（最常见的原因 - - 多余的空格，或来自错误环境的密钥）、发送方是否使用了其他端点的密钥，以及在“标准 Webhook”与应用之间是否有任何环节重写了请求体。 签名覆盖原始字节，因此会重新格式化 JSON 的代理会破坏签名。Webhook 页面上的签名测试工具会显示被签名的确切文本。
每次请求都会返回 401 错误
请确认 Webhook 的身份验证方式已设置为 HMAC，且已选择**“标准 Webhook”**提供商；确认已填写密钥；并确认“标准 Webhook”向 URL 发送的数据与应用中显示的完全一致，包括末尾的代码。
“历史”中没有显示任何内容
该请求从未送达。请在“标准 Webhook”中重新检查 URL，并查看“标准 Webhook”自身的投递日志，了解其收到的响应。如果显示 404，则表示 Webhook 错误或已被删除；如果显示 429，则表示您已超过套餐的调用限制 - - 请参阅 套餐与使用情况。
工作流程针对错误的事件运行
您商店中的每个 Webhook 都会触发同一个 Shopify Flow 触发器。请在工作流程的第一步中添加一个基于 Webhook ID 的条件，或者缩小从“标准 Webhook”发送的事件范围。
请求失败，错误信息为“时间戳超出容差范围”
Standard Webhook 会对时间戳进行签名，而应用程序会拒绝任何超过 5 分钟的时间戳。这通常是发送方的时间同步问题，或者是 Standard Webhook 在很久之后使用原始时间戳重试发送的结果。来自同一原始请求的重试无法通过；请让 Standard Webhook 发送一个新的事件。
相关
- 验证已签名的 Webhook - 我们核实的每家服务提供商，以及如何描述未核实的服务提供商。
- 负载映射和流变量 - 从负载中提取正确的字段并导入 Shopify Flow。
- 重复配送防护 - 当标准 Webhook 重试发送时会发生什么。
- 历史与故障排除 - 每个请求的日志，并支持回放。