身份验证

任何知道 Webhook URL 的人都可以向其发送请求，因此身份验证能防止陌生人触发您的 Shopify Flow 工作流程。请在每个 Webhook 的**“安全**”部分中进行设置。

这三种方法

方法	调用方如何证明自身身份	在以下情况下使用它：
无	没有	仅用于测试 - - 绝不用于生产环境
静态令牌	请求头中的固定密钥	几乎所有的集成（n8n、Make、Zapier、您自己的代码）
HMAC SHA-256	根据请求和共享密钥计算出的签名	发送方对其 Webhook（Stripe、GitHub、Slack 等）进行签名

静态令牌

点击 Webhook 上的“生成”按钮以获取一个强随机令牌，或粘贴您自己的令牌。调用方将其作为标头发送：

Webhook 编辑器：左侧为名称和身份验证，右侧为包含状态、Webhook URL 和 Webhook ID 的“端点”卡片，上方依次为“实时预览”、“测试”和“使用情况” — 静态令牌：选择发送方传递令牌的方式，生成或粘贴令牌，并从“端点”卡片中复制 Webhook URL。

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001"}'

更改表头名称

某些系统只能发送其已使用的标头。请在“高级设置”中设置**“Auth”标头名称**，我们将从该标头中读取令牌，而不是从X-Api-Key中读取：

bash

  -H "X-Custom-Auth: your-token"

标头名称不区分大小写。保留名称将被拒绝 - - 例如：Host、Authorization、Cookie、X-Forwarded-*、X-Webhook-*、CF-* 以及类似名称。这些标头由代理服务器和 CDN 设置或重写，因此从其中读取的令牌可能会被攻击者控制。

令牌的流转路径

并非每个发送方都能添加任意的标头。**发送方如何传递令牌？**在“Webhook”选项卡中提供了四个位置：

选择	发件人发送	在以下情况下使用它：
在自定义页眉中	`X-Api-Key: <token>`，或您选择的标头名称	默认设置，也是大多数集成所采用的方式
作为无记名代币	`Authorization: Bearer <token>`	该工具包含一个“Bearer”或“API令牌”字段
作为用户名和密码	HTTP Basic 认证，用户名由您自行选择，令牌作为密码	该工具仅支持基本认证
在 URL 中	`?token=<token>`，或您选择的参数名称	发送方只能调用普通 URL，无法设置请求头

Authorization 特意保留了一个预留的_自定义_标头名称：支持使用“Bearer”和“Basic”两种方式，系统会自动处理这两种情况。在这两种情况下，401请求还会携带一个WWW-Authenticate标头，因为部分HTTP客户端只有在收到身份验证请求后才会发送凭据。

URL 选项是这四种方法中最不安全的 - - URL 最终会出现在日志、引荐来源和浏览器历史记录中 - - 因此，请仅在发件人别无选择时才使用它。该应用会显示包含令牌的最终 URL，并在存储请求的任何地方对该参数进行屏蔽。

HMAC SHA-256

发送方使用共享密钥对请求计算签名；我们重新计算该签名并进行比对。泄露的请求无法通过篡改内容进行重放，因为请求体将不再与签名匹配。

提供商预设

在**“签名提供商**”下选择您的签名提供商，我们将根据该提供商的具体方案进行验证 - - 包括标头名称、编码方式、签名内容以及签名的有效期。将该提供商控制面板中的签名密钥粘贴进来即可完成设置。

共有 22 个内置提供商，每个提供商都有相应的设置指南：Calendly、Customer.io、GitHub、Lemon Squeezy、Linear、Mollie、Paddle、Paystack、Razorpay、Sanity、Sendcloud、Sentry、Shopify、 Slack、Square、标准 Webhook（OpenAI、Supabase）、Stripe、Svix（Clerk、Resend）、Typeform、Vercel、WooCommerce 和 Zendesk。如果您的服务未列在其中，请描述它如何通过自定义方案进行签名。

完整列表、自定义选项和内置签名测试工具，请参见验证已签名的 Webhook。

一个采用 HMAC 认证且使用 Stripe 作为签名提供商的 Webhook，展示了“签名密钥”字段、该字段的验证内容以及“连接 Stripe”的步骤 — 已签名的发送方（此处为 Stripe）：选择服务提供商，粘贴其签名密钥，编辑器会显示已勾选的内容以及如何进行连接。

通用 HMAC

由于既没有预设方案，也没有自定义方案，我们采用自己的方案：调用方发送 X-Signature，即使用签名密钥对 X-Webhook-* 头信息值计算得到的 HMAC-SHA256 值。

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Data: value1value2" \
  -H "X-Signature: <hmac-sha256 of the X-Webhook-* values>" \
  -d '{"data":"payload"}'

拒绝是什么样子的

身份验证失败时会返回 401，其 JSON 正文中会注明原因 - - 完整的代码列表请参见历史与故障排除。在您编辑 Webhook 期间，被拒绝的调用仍会显示在“实时请求检查器”中，因此您可以准确了解调用被拒的原因。

在不影响服务的情况下轮换密钥

一步更改密钥意味着，所有使用旧密钥签名的请求都会失败，直到发送方完成更新为止。通过 Webhook 轮换密钥可以避免这种情况：它会保留第二个有效的密钥，该密钥与主密钥同时被接受，适用于静态令牌和所有签名方案。

将新密钥输入到**“第二个有效密钥**”中，然后保存。现在这两个密钥均被接受。
将发件人切换到新的密钥。
点击**“推广**”，将其移至主字段并清空第二个字段，然后保存。

在任何情况下都不会拒绝任何请求。第二个密钥的存储方式与主密钥完全相同，且 API 绝不会返回该密钥本身 - - 只会返回该密钥是否已设置。

妥善保管这个秘密

无论在何种访问级别，我们的 REST API 或 MCP 服务器都不会返回该令牌 - - 它们仅报告是否已设置。参见开发者 API 和 MCP。
该数据在静止状态下已加密。
旋转后会立即生效，因此请使用上文提到的“第二秘技”Shopify Flow，而不是覆盖主字段。
存储的调用历史记录会隐藏身份验证标头、Basic 凭据和 URL 令牌，因此，历史记录的截图并不会泄露你的秘密。

进一步缩小范围

身份验证可证明调用者知晓密钥。源验证（IP白名单）限制了调用的来源，并可与上述任何一种模式结合使用。