網路鉤子 (Webhook)

Webhook 使用方法

您可以註冊網路鉤子，讓應用程式即時接收 Gency 內部發生的事件。

網路鉤子註冊

在 API 中心點擊 建立新網路鉤子 並輸入以下項目。

名稱（必填，最多 100 字）：可識別網路鉤子的名稱
URL（必填，僅允許 HTTPS，最多 500 字）：事件發生時發送 POST 請求的端點
訂閱事件：以核取方塊選擇要接收的事件類型

支援的事件類型

事件	說明
`product.created`	商品已建立
`product.deleted`	商品已刪除
`product.pending_review`	已變更為待檢核狀態
`product.in_review`	已變更為檢核進行中
`product.review_completed`	檢核已完成
`product.creation_failed`	商品建立失敗

事件酬載

事件發生時會向已註冊的 URL 發送以下格式的 POST 請求。event 欄位為共通，data 內部結構會依事件類型而不同。

product.pending_review / product.in_review / product.review_completed

商品的檢核狀態變更時發送。

{
  "event": "product.review_completed",
  "data": {
    "products": [
      {
        "workspaceId": "01HABC...",
        "productId": "01HXYZ...",
        "projectId": "my-project-01",
        "productName": "겨울 패딩 자켓",
        "status": "REVIEW_COMPLETE",
        "category": "OUTER",
        "productType": "FASHION",
        "createdId": "01HUSR...",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

欄位	類型	說明
`products`	Array	狀態變更的商品清單
`products[].workspaceId`	String	工作區 ID
`products[].productId`	String	商品 ID
`products[].projectId`	String	管理名稱
`products[].productName`	String	商品名稱
`products[].status`	String	變更後的狀態 (`BEFORE_REVIEW`: 檢核前, `IN_REVIEW`: 檢核中, `REVIEW_COMPLETE`: 檢核完成, `CREATION_FAILED`: 建立失敗)
`products[].category`	String	類別
`products[].productType`	String	商品類型 (`FASHION`, `JEWELRY`)
`products[].createdId`	String	建立者 ID
`products[].createdAt`	String	建立日期時間 (ISO 8601)

product.created

商品建立時發送。

{
  "event": "product.created",
  "data": {
    "products": [
      {
        "workspaceId": "01HABC...",
        "productId": "01HXYZ...",
        "projectId": "my-project-01",
        "productName": "겨울 패딩 자켓",
        "status": "BEFORE_REVIEW",
        "category": "OUTER",
        "productType": "FASHION",
        "createdId": "01HUSR...",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

product.creation_failed

商品建立失敗時發送。

{
  "event": "product.creation_failed",
  "data": {
    "products": [
      {
        "workspaceId": "01HABC...",
        "productId": "01HXYZ...",
        "projectId": "my-project-01",
        "productName": "겨울 패딩 자켓",
        "status": "CREATION_FAILED",
        "category": "OUTER",
        "productType": "FASHION",
        "createdId": "01HUSR...",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

酬載結構與狀態變更事件相同。status 會設定為 PRODUCT_STATUS_05（建立失敗）。

product.deleted

商品刪除時發送。

{
  "event": "product.deleted",
  "data": {
    "products": [
      {
        "workspaceId": "01HABC...",
        "productId": "01HXYZ...",
        "productName": "겨울 패딩 자켓"
      }
    ]
  }
}

欄位	類型	說明
`products`	Array	已刪除的商品清單
`products[].workspaceId`	String	工作區 ID
`products[].productId`	String	商品 ID
`products[].productName`	String	商品名稱

重試策略

網路鉤子發送失敗時，系統會自動重試。包含最初發送在內最多嘗試 5次（最初 1 次 + 重試 4 次），並以 指數退避 方式拉長間隔。

成功基準：HTTP 回應代碼 200 ~ 299
失敗處理：上述範圍外的回應代碼、逾時（30 秒）、網路錯誤等皆視為失敗。
5 次重試全部失敗時，該次遞送即處理為 最終失敗。
所有嘗試的遞送紀錄（HTTP 狀態代碼、回應時間、錯誤訊息）會保存 30 天。

網路鉤子註冊限制

每個 master 最多可註冊 10 個 網路鉤子。已刪除的網路鉤子不計入數量，因此達到上限時，刪除未使用的網路鉤子即可重新註冊。

簽章驗證（選用）

建立網路鉤子時會自動發行 Signing Secret（whsec_{32자 랜덤문자열} 格式）。簽章驗證並非必要，但為了防止偽造的請求，建議在正式環境中進行驗證。

每個網路鉤子請求皆包含以下標頭。

標頭	說明
`X-Webhook-Signature`	`sha256={HMAC-SHA256 서명값}`
`X-Webhook-Timestamp`	請求發送時間 (Unix timestamp)
Content-Type	application/json

驗證方法：

從 X-Webhook-Timestamp 標頭擷取時間戳記。
以 {타임스탬프}.{요청 body} 格式建立簽章對象訊息。
以 Signing Secret 作為金鑰計算 HMAC-SHA256 簽章。
比對計算出的簽章與 X-Webhook-Signature 標頭的值。

// 검증 예시 (Java)
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;

public boolean verifyWebhook(String payload, String timestamp, String signature, String secret) {
    String message = timestamp + "." + payload;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
    byte[] hash = mac.doFinal(message.getBytes());
    StringBuilder hex = new StringBuilder();
    for (byte b : hash) {
        hex.append(String.format("%02x", b));
    }
    String expected = "sha256=" + hex.toString();
    return MessageDigest.isEqual(expected.getBytes(), signature.getBytes());
}

Secret 重新發行

點擊 Secret 重新發行 按鈕後會發行新的 Signing Secret。既有密鑰會立即失效，因此須在新密鑰套用至伺服器後再使用。

狀態管理

網路鉤子可具有以下狀態。

狀態	說明
`ACTIVE`	事件發生時正常發送
`INACTIVE`	暫停事件發送

若想暫時中斷網路鉤子的接收，可將其停用；若刪除則會完全移除。

Webhook 使用方法​

網路鉤子註冊​

支援的事件類型​

事件酬載​

product.pending_review / product.in_review / product.review_completed​

product.created​

product.creation_failed​

product.deleted​

重試策略​

網路鉤子註冊限制​

簽章驗證（選用）​

Secret 重新發行​

狀態管理​