【揭密协议 之一】拆解 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/