开发者 API 和 MCP
您在应用中管理的所有内容，也可以通过您自己的代码或 AI 助手进行管理。Workflow Webhooks 提供了两个接口：REST API 和 MCP 服务器。这两个接口均位于“开发者”页面上。
API密钥
这两个平台均通过 API 密钥进行身份验证。在**“开发者**”页面下的**“API 密钥**”部分，创建一个密钥并选择其访问级别：
- 只读 - 列出 Webhook、查看调用历史记录和统计信息。
- 读写 - - 还可创建、更新和删除 Webhook。
- 读取、写入和执行 - - 还可以触发一次测试调用或重放之前的调用。
完整密钥仅在创建时显示一次。请届时将其复制并安全保存；此后您将无法再次查看该密钥。密钥以哈希形式存储，绝不会以明文形式存储，且您可以随时撤销该密钥。
在每次请求中将密钥作为 Bearer 令牌发送：
Authorization: Bearer fwk_your_key_here为什么“执行”是一个独立的层级
触发 Webhook 确实会运行您的 Shopify Flow 工作流程，而这些工作流程可能会对您的商店产生影响 - - 例如给订单打标签、发送电子邮件、更新库存。将此功能隔离在独立层级中，意味着您交给脚本或 AI 助手用于日常工作的密钥，不会意外触发您的自动化流程。 默认情况下只发放读取密钥，仅在确实需要时才创建执行密钥。
基础网址
API 和 MCP 服务器通过一个专用主机名提供服务：
https://shopify.workflow-webhooks.app因此，REST API 的地址为 https://shopify.workflow-webhooks.app/api/v1，MCP 服务器的地址为 https://shopify.workflow-webhooks.app/api/mcp。在“开发者”页面上，这两个地址都配有“复制”按钮。
该主机名仅用于访问 /api - - 嵌入式管理界面则保留其独立的 Shopify 注册网址。将两者分开意味着，您粘贴到脚本、CI 任务或 AI 客户端中的地址是稳定的，且与应用的嵌入方式无关。
REST API
基础 URL 显示在“开发者”页面上。主要端点如下：
| 方法 | 路径 | 级别 | 目的 |
|---|---|---|---|
| GET | /api/v1 |
无 | API 指数 - - 确认 API 正常运行 |
| GET | /api/v1/me |
阅读 | 检查身份验证并查看密钥的级别 |
| GET | /api/v1/webhooks |
阅读 | 列出 Webhook |
| POST | /api/v1/webhooks |
写 | 创建一个 Webhook |
| GET | /api/v1/webhooks/:id |
阅读 | 获取一个 Webhook |
| PUT / PATCH | /api/v1/webhooks/:id |
写 | 更新一个 Webhook |
| DELETE | /api/v1/webhooks/:id |
写 | 删除一个 Webhook |
| POST | /api/v1/webhooks/:id/test |
执行 | 执行一次测试调用 |
| GET | /api/v1/history |
阅读 | 列表调用 |
| GET | /api/v1/history/:id |
阅读 | 获取一次调用及其负载 |
| POST | /api/v1/history/:id/replay |
执行 | 重放过去的调用 |
| GET | /api/v1/stats |
阅读 | 总计、成功率、每日数据系列 |
| GET | /api/v1/templates |
阅读 | 内置的 Webhook 模板 |
快速检查一下您的密钥是否有效：
curl https://shopify.workflow-webhooks.app/api/v1/me \
-H "Authorization: Bearer fwk_your_key_here"{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }MCP 服务器
MCP 服务器允许人工智能助手（如 Claude、Cursor、VS Code、Gemini CLI 等）在对话中与您的 Webhook 进行交互。在“开发者”页面上的“MCP”选项卡中，会显示服务器 URL 以及针对每个客户端的、可直接复制的连接命令，其中已预先填入了您的密钥。
这些工具与 REST 端点相对应，且工具集取决于您的密钥级别：只读密钥甚至无法访问用于创建、删除或触发 Webhook 的工具。所有身份验证和数据处理均在服务器端进行。
您的数据如何得到保护
在将自动化工具或人工智能助手对接到此 API 之前，有两点值得了解。
**您的 Webhook 的认证令牌始终不可读取。**您在 Webhook 上设置的令牌或签名密钥，无论在哪个层级，都无法通过 API 或 MCP 读取。响应仅会告知您令牌是否已设置（hasToken），绝不会透露其具体值。您可以设置新的令牌，但永远无法检索旧的令牌。
**负载中的个人数据已被屏蔽。**Webhook 负载来自外部系统，通常包含客户详细信息。 在调用负载离开服务器之前，所有看似个人数据的值都会被替换为 ***：包括电子邮件地址、电话号码、卡号，以及以人名命名的字段（如 customerName、shippingAddress 等）。请求头部的处理方式与应用的历史记录界面一致。
这种屏蔽处理虽然谨慎，但并非万无一失。它仅对字段名称和值模式起作用，因此自由文本字段中包含的个人数据 - - 例如备注、评论或消息正文 - - 仍可能泄露。请将 API 响应视为可能包含客户数据，并据此进行存储。
**测试和重放不会占用您的配额。**您通过 API 发起的调用会被记录为测试，因此不会计入您套餐的月度配额。重放也不会计入配额，因为原始调用已经计入其中。
下一步
- Workflow Webhooks 简介 - Webhook 和负载映射的工作原理。
速率限制
REST API 和 MCP 服务器每个 API 密钥共用一个配额。
- 每个密钥每60秒300次请求，作为固定时间窗口。
- **执行级调用还有第二项更严格的配额限制，即每小时60次。**这两项配额都会被消耗，因此执行操作的突发峰值也会占用共享配额。对于该应用而言，这意味着测试调用Webhook和重放历史条目 - - 这两项操作实际上都会触发您的Shopify Flow工作流程。
- **所有套餐均是如此。**您的套餐按调用次数计费，而非按API调用次数计费，因此升级套餐不会增加这些数值。
- 处理时返回 HTTP 429 状态码。请延迟一段时间后再试，最好采用指数退避算法。
- 如果我们的缓存短暂不可用，限流器会采取“限流失败时保持开放”的机制，而不是阻断您的集成。
传入的 Webhook 不受速率限制
这一点值得明确说明，因为这是我们被问到最多的问题：**我们不会限制传入 Webhook 的发送速度。**我们会以源系统产生的任何突发流量速度，在 Webhook 到达的瞬间立即将其发送出去 - - 我们这边没有每秒或每分钟的上限。
唯一的限制是您套餐中30天的调用配额。一旦配额用完，后续调用将不再被处理，直到配额周期重置或您升级套餐。除此之外，还需遵守Shopify的限制：Shopify Flow 设有自身的执行限制，且触发器有效负载上限为50KB。
Shopify
这些是Shopify对Shopify API设定的限制，并非我们设定的。这些限制适用于该应用（以及您的工作流程）在Shopify端的功能，因此即使您完全在我们的限制范围内，在大型商店中也可能遇到这些限制。
- 所有 Shopify API 的输入数组均限制为 250 个元素。包含超过此限制的数组的请求将被拒绝。
- **分页在 25,000 个对象处停止。**计数在 25,000 以内是准确的；超过该数值时，Shopify 会返回
25001，表示“超过 25,000”。如果需要进一步查询，请先进行筛选。 - GraphQL 管理 API 根据计算出的查询成本（以每秒点数为单位）进行计费，其上限取决于商店的 Shopify 套餐：
| Shopify 套餐 | 每秒得分 |
|---|---|
| 标准 | 100 |
| 高级 | 200 |
| 此外 | 1000 |
| 企业（商务组件） | 2000 |
店面 API 没有速率限制。
详细信息：Shopify API 速率限制