跳至主要內容
STOAR STOAR

對外 Webhook

已簽章的事件通知

最後更新：2026年9月5日

Webhook 會即時將商店事件推送到您自己的系統——把訂單同步到 ERP、通知 3PL、觸發自動化流程，或更新資料倉儲。每當已訂閱的事件發生時，STOAR 就會對您的端點送出一個已簽章的 JSON POST。

建立端點 #

前往 後台 → REST API → Webhooks → 建立：

  1. 輸入您的 Payload URL（STOAR 要 POST 的目標位址）。
  2. 選取您想接收的主題。
  3. 儲存——STOAR 會為該端點產生一組簽章密鑰（編輯時可以看到）。

主題 #

主題 觸發時機
order.paid 訂單已付款
order.refunded 訂單已退款
order.cancelled 訂單已取消
customer.created 顧客完成註冊
product.created 商品已建立
product.updated 商品已更新
product.deleted 商品已刪除

內容與驗證 #

每一次傳送都是一個 JSON POST：

{
  "topic": "order.paid",
  "created_at": "2026-06-13T10:00:00+00:00",
  "data": { "id": 123, "order_number": "ORD-000123", "total_amount": 92.50, "currency": "USD", ... }
}

標頭：

  • X-Stoar-Topic——事件主題
  • X-Stoar-Delivery——傳送 ID
  • X-Stoar-Signature——以端點密鑰對原始內文計算的 sha256=<hmac>

請以您的簽章密鑰對原始請求內文計算 HMAC-SHA256，並與簽章標頭比對，以驗證每一個請求。不相符的請求應予以拒絕。

傳送與重試 #

  • 傳送會排入佇列並於背景送出。
  • 非 2xx 的回應或逾時會以退避策略重試數次。
  • 每一次嘗試（狀態、HTTP 代碼、錯誤）都會記錄在後台該端點的傳送記錄中，讓您清楚看到送出了什麼、以及您的端點如何回應。

注意事項 #

  • 端點可以停用而不必刪除。
  • 請讓您的處理程式具備冪等性——使用 X-Stoar-Delivery 來去除重試傳送的重複資料。