開發者 API 與 MCP
您在應用程式中管理的一切，亦可透過您自己的程式碼或 AI 助理來管理。Workflow Webhooks 提供兩個介面：REST API 和 MCP 伺服器。這兩者皆位於「**開發者」**頁面中。
API 金鑰
這兩項服務皆透過 API 金鑰進行驗證。請至**「開發者**」頁面中的「API 金鑰」區段，建立一個金鑰並選擇其存取層級：
- 唯讀權限 - - 列出 Webhooks、讀取呼叫記錄及統計資料。
- 讀取與寫入 - - 亦可建立、更新及刪除 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 伺服器可讓 AI 助理（例如 Claude、Cursor、VS Code、Gemini CLI 等）在對話中與您的 webhook 進行互動。在「開發者」頁面中，「MCP」分頁會顯示伺服器網址，以及針對每個客戶端已預先填入您的金鑰、可直接複製的連接指令。
這些工具與 REST 端點相對應，且工具集會根據您的金鑰等級而有所不同：唯讀金鑰甚至無法看到用於建立、刪除或觸發 Webhook 的工具。所有身份驗證與資料處理皆在伺服器端進行。
您的資料如何受到保護
在將自動化工具或 AI 助理對準此 API 之前，有兩件事值得了解。
**您的 Webhook 授權代幣絕不會被讀取。**您在 Webhook 上設定的代幣或簽名密鑰，無論在何種層級，都無法透過 API 或 MCP 讀取回來。回應僅會告知您代幣是否已設定（hasToken），絕不會顯示其數值。您可以設定新的代幣，但絕無法取得舊的代幣。
**載荷中的個人資料已進行遮罩處理。**Webhook 載荷來自外部系統，通常包含客戶詳細資料。 在呼叫載荷離開伺服器之前，任何看似個人資料的值都會被替換為 ***：電子郵件地址、電話號碼、卡號，以及以人名命名的欄位（例如 customerName、shippingAddress 等）。請求標頭的清理方式與應用程式的歷史紀錄畫面相同。
這種遮蔽處理雖已謹慎執行，但無法保證萬無一失。由於此機制僅針對欄位名稱與值模式進行處理，因此存放在自由文字欄位中的個人資料 - - 例如備註、評論或訊息正文 - - 仍可能外洩。請將 API 回應視為可能包含客戶資料，並據此妥善儲存。
**測試與重播不會佔用您的配額。**您透過 API 發起的呼叫會被記錄為測試，因此不會計入您方案的每月配額。重播同樣不會佔用配額，因為原始呼叫已經計入配額了。
下一步
- 《Workflow Webhooks》簡介 - Webhooks 和有效載荷映射的運作原理。
速率限制
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 |
Storefront API 並無速率限制。
完整詳情：Shopify API 請求限制