【揭密協議 之一】拆解 AI Ready 核心通訊協定：API Payload 與 Webhook 安全驗證

直接答案：AI Ready 協議應把 AI 任務從「一段 prompt」提升為可治理的 API 事件。每個請求都要包含 intent、source、context、data、constraints 與 idempotency key；Webhook 則必須有 timestamp、nonce、signature 與重放防護。

這篇文章適合誰？#

• 電商系統核心開發工程師。

• 需要設計 AI 任務 API 的後端與架構師。

• 負責 webhook 安全、重試與審計的技術團隊。

為什麼 AI 任務需要通訊協定？#

如果每個外掛都自己把 prompt 丟給模型，系統會很難回答以下問題：

• 這次任務是誰觸發的？

• AI 可以讀哪些資料？

• AI 是否可以回寫？

• 任務使用哪個語系與店鋪？

• token 預算是多少？

• 失敗後是否可以重試？

• 重複 webhook 是否會造成重複操作？

AI Ready 協議的目的，是把這些治理資訊放進每次任務，而不是散落在程式碼與 prompt 裡。

Request Payload 基本結構#

{
  "event_id": "evt_20260415_001",
  "idempotency_key": "product-copy-1288-zhTW-v3",
  "intent": "generate_product_copy",
  "source": {
    "platform": "woocommerce",
    "store_id": "tw-store",
    "site_url": "https://example.com"
  },
  "context": {
    "locale": "zh-TW",
    "currency": "TWD",
    "actor": {
      "type": "admin",
      "id": "42"
    },
    "permissions": ["product:read", "draft:write"]
  },
  "data": {
    "product": {
      "sku": "BAG-18L-NAVY",
      "name": "18L 防潑水通勤背包",
      "attributes": {
        "capacity": "18L",
        "material": "recycled polyester"
      }
    }
  },
  "constraints": {
    "write_mode": "draft_only",
    "max_tokens": 1200,
    "do_not_change": ["sku", "price", "stock_quantity"]
  }
}

每個欄位都應有明確意義：

• event_id：事件唯一識別。

• idempotency_key：避免重試造成重複操作。

• intent：任務類型。

• source：來源平台與店鋪。

• context：語系、幣別、操作者與權限。

• data：任務所需資料。

• constraints：模型與回寫限制。

Response Payload 基本結構#

{
  "event_id": "evt_20260415_001",
  "status": "completed",
  "result": {
    "draft_short_description": "適合日常通勤的 18L 防潑水背包。",
    "meta_description": "18L 防潑水通勤背包，適合筆電收納與城市移動。"
  },
  "validation": {
    "schema_valid": true,
    "requires_review": true
  },
  "usage": {
    "model": "provider-model-name",
    "input_tokens": 680,
    "output_tokens": 220
  }
}

回應不應只包含文字，還要包含驗證狀態、審核需求與 token 用量。

Webhook 簽章設計#

建議 header：

X-AI-Ready-Timestamp: 1776268800
X-AI-Ready-Nonce: 4a8f7c...
X-AI-Ready-Signature: sha256=...
X-AI-Ready-Event-Id: evt_20260415_001
Idempotency-Key: product-copy-1288-zhTW-v3

簽章內容可使用 canonical string：

{timestamp}.{nonce}.{raw_body}

再以共享密鑰做 HMAC SHA-256。接收端應：

1. 檢查 timestamp 是否在允許時間窗內。
2. 檢查 nonce 是否已使用。
3. 用 raw body 重算簽章。
4. 檢查 event id 與 idempotency key。
5. 保存處理狀態。

HTTP 狀態碼與重試#

• 200 / 204：成功處理或已處理過。

• 400：payload 格式錯誤，不應重試。

• 401 / 403：簽章或權限錯誤，不應重試直到設定修正。

• 409：idempotency conflict，需人工檢查。

• 422：schema validation 失敗，不應自動回寫。

• 429：速率限制，可延遲重試。

• 500 / 503：暫時性錯誤，可重試。

FAQ#

HMAC 簽章是否就足夠安全？#

HMAC 是重要基礎，但還需要 timestamp、nonce、idempotency、密鑰輪替、TLS、最小權限與日誌。只做簽章仍無法防止重放與重複執行。

Webhook 可以直接修改商品或訂單嗎？#

不建議直接修改高風險資料。Webhook 應先寫入草稿、審核佇列或低風險欄位。改價、退款、發券等操作需要額外核准。

為什麼需要 idempotency key？#

Webhook 或背景任務可能重試。沒有 idempotency key，系統可能重複寄信、重複建立折扣碼或重複回寫內容。

參考資料#

• OWASP Webhook Security Guidelines，https://cheatsheetseries.owasp.org/
• WordPress REST API Handbook，https://developer.wordpress.org/rest-api/
• Adobe Commerce Web APIs，https://developer.adobe.com/commerce/webapi/