[Revealed Protocol 1] Dismantling the core communication protocol of AI Ready: API Payload and Webhook security verification

Direct answer: The AI Ready protocol should elevate AI tasks from "a prompt" to manageable API events. Each request must contain intent, source, context, data, constraints and idempotency key; Webhook must have timestamp, nonce, signature and replay protection.

Who should read this?#

• Ecommerce system core development engineer.

• Backend and architect required to design AI task API.

• Technical team responsible for webhook security, retries and auditing.

Why do AI tasks require communication protocols?#

If each plugin throws prompt to the model, it will be difficult for the system to answer the following questions:

• Who triggered this mission?

• What information can AI read?

• Can AI write back?

• Which language and store are used for the task?

• What is the token budget?

• Is it possible to try again after failure?

• Will duplicate webhooks cause duplicate operations?

The purpose of the AI Ready protocol is to put this management information into every task, rather than being scattered in the program code and prompts.

Request Payload basic structure#

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

Each field should have a clear meaning:

• event_id: unique identification of the event.

• idempotency_key: avoid repeated operations caused by retries.

• intent: task type.

• source: source platform and store.

• context: language, currency, operator and permissions.

• data: the data required for the task.

• constraints: model and write-back restrictions.

Response Payload basic structure#

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

The response should not only contain text, but also include verification status, review requirements, and token usage.

Webhook signature design#

Suggested 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

The signature content can use canonical string:

{timestamp}.{nonce}.{raw_body}

Then do HMAC SHA-256 with the shared key. The receiving end should:

1. Check whether timestamp is within the allowed time window.
2. Check whether the nonce is used.
3. Use raw body to recalculate the signature.
4. Check event id and idempotency key.
5. Save the processing status.

HTTP status codes and retries#

• 200 / 204: Successfully processed or already processed.

• 400: The payload format is incorrect and should not be retried.

• 401 / 403: Signature or permission error, should not be retried until settings are corrected.

• 409: idempotency conflict, manual inspection is required.

• 422: schema validation failed and should not be automatically written back.

• 429: Rate limiting, retry can be delayed.

• 500 / 503: Temporary error, you can try again.

FAQ#

Is an HMAC signature secure enough?#

HMAC is an important foundation, but timestamp, nonce, idempotency, key rotation, TLS, least privileges and logging are also needed. Just signing cannot prevent replay and repeated execution.

Can Webhook directly modify products or orders?#

It is not recommended to directly modify high-risk data. Webhooks should be written to draft, review queue, or low-risk fields first. Operations such as price changes, refunds, and coupon issuance require additional approval.

Why do I need an idempotency key?#

The webhook or background task may be retried. Without an idempotency key, the system may send emails repeatedly, create discount codes repeatedly, or write back content repeatedly.

References#

• 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/