【公開されたプロトコル1】AI Readyのコア通信プロトコルの解体：APIペイロードとWebhookのセキュリティ検証

直接の答え: AI Ready プロトコルは、AI タスクを「プロンプト」から管理可能な API イベントに昇格させる必要があります。各リクエストには、インテント、ソース、コンテキスト、データ、制約、冪等性キーが含まれている必要があります。 Webhook にはタイムスタンプ、ノンス、署名、およびリプレイ保護が必要です。

この記事の対象読者#

• ECシステムコア開発エンジニア。

• AI タスク API を設計するにはバックエンドとアーキテクトが必要です。

• Webhook のセキュリティ、再試行、監査を担当する技術チーム。

AI タスクに通信プロトコルが必要なのはなぜですか?#

各プラグインがモデルにプロンプトをスローすると、システムが次の質問に答えることが困難になります。

• このミッションを引き起こしたのは誰ですか? ――AIはどのような情報を読み取れるのでしょうか？

• AIは書き戻すことができますか?

• タスクにはどの言語とストアが使用されますか?

• トークンの予算はどれくらいですか?

• 失敗しても再度挑戦することは可能ですか?

• Webhook が重複すると操作の重複が発生しますか?

AI Ready プロトコルの目的は、この管理情報をプログラム コードやプロンプトに散在させるのではなく、すべてのタスクに組み込むことです。

リクエストペイロードの基本構造#

{
  "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: モデルとライトバックの制限。

レスポンスペイロードの基本構造#

{
  "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
  }
}

応答にはテキストだけでなく、検証ステータス、レビュー要件、トークンの使用状況も含める必要があります。

Webhook 署名のデザイン#

推奨されるヘッダー:

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

署名の内容には正規の文字列を使用できます。

{timestamp}.{nonce}.{raw_body}

次に、共有キーを使用して HMAC SHA-256 を実行します。受信側は次のことを行う必要があります。

1. タイムスタンプが許可された時間枠内であるかどうかを確認します。
2. nonceが使用されているかどうかを確認します。
3. 生の本文を使用して署名を再計算します。
4. イベント ID と冪等キーを確認します。
5. 処理状況を保存します。

HTTP ステータス コードと再試行#

• 200 / 204: 正常に処理されたか、すでに処理されました。

• 400: ペイロード形式が正しくないため、再試行しないでください。

• 401 / 403: 署名または権限エラー。設定が修正されるまで再試行しないでください。

• 409: 冪等性の競合。手動検査が必要です。

• 422: スキーマ検証が失敗したため、自動的に書き戻されるべきではありません。

• 429: レート制限、再試行を遅らせることができます。

• 500 / 503: 一時的なエラー。再試行できます。

よくある質問#

HMAC 署名は十分に安全ですか?#

HMAC は重要な基盤ですが、タイムスタンプ、ノンス、冪等性、キー ローテーション、TLS、最小権限、ログも必要です。署名するだけでは、リプレイや繰り返しの実行を防ぐことはできません。

Webhook は商品や注文を直接変更できますか?#

リスクの高いデータを直接変更することはお勧めできません。 Webhook は、最初にドラフト、レビュー キュー、または低リスク フィールドに書き込む必要があります。価格変更、返金、クーポン発行などの操作には追加の承認が必要です。

冪等キーが必要なのはなぜですか?#

Webhook またはバックグラウンド タスクが再試行される可能性があります。冪等キーがないと、システムは電子メールを繰り返し送信したり、割引コードを繰り返し作成したり、コンテンツを繰り返し書き戻したりする可能性があります。

参考資料#

• OWASP Webhook セキュリティ ガイドライン、https://cheatsheetseries.owasp.org/
• WordPress REST API ハンドブック、https://developer.wordpress.org/rest-api/
• Adobe Commerce Web API、https://developer.adobe.com/commerce/webapi/