[Раскрытый протокол 1] Демонтаж основного протокола связи AI Ready: проверка безопасности API Payload и Webhook

Прямой ответ: протокол AI Ready должен поднять задачи ИИ из «подсказки» в управляемые события API. Каждый запрос должен содержать намерение, источник, контекст, данные, ограничения и ключ идемпотентности; Вебхук должен иметь временную метку, одноразовый номер, подпись и защиту от повторного воспроизведения.

Для кого эта статья?#

• Инженер-разработчик ядра системы электронной коммерции.

• Требуется бэкенд и архитектор для разработки API задач ИИ.

• Техническая группа, отвечающая за безопасность веб-перехватчиков, повторные попытки и аудит.

Почему задачи ИИ требуют протоколов связи?#

Если каждый плагин будет выдавать подсказку модели, системе будет сложно ответить на следующие вопросы:

• Кто инициировал эту миссию?

• Какую информацию может прочитать ИИ?

• Может ли ИИ написать ответ?

• Какой язык и магазин используются для выполнения задачи?

• Каков бюджет токена?

• Можно ли после неудачи повторить попытку?

• Будут ли дублированные веб-хуки вызывать дублирование операций?

Цель протокола 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: избежать повторных операций, вызванных повторными попытками.

• намерение: тип задачи.

• source: исходная платформа и хранилище.

• «контекст»: язык, валюта, оператор и права доступа.

• данные: данные, необходимые для задачи.

• ограничения: ограничения модели и обратной записи.

Базовая структура полезной нагрузки ответа#

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

Ответ должен содержать не только текст, но также статус проверки, требования к проверке и использование токена.

Дизайн подписи вебхука#

Предлагаемый заголовок:

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. Проверьте идентификатор события и ключ идемпотентности.
5. Сохраните статус обработки.

Коды состояния HTTP и повторные попытки#

• 200 / 204: успешно обработано или уже обработано.

• 400: формат полезных данных неверен, и его не следует повторять.

• 401 / 403: ошибка подписи или права доступа, не следует повторять попытку, пока настройки не будут исправлены.

• 409: конфликт идемпотентности, требуется проверка вручную.

• 422: проверка схемы не удалась и не должна автоматически записываться обратно.

• 429: ограничение скорости, повторная попытка может быть отложена.

• 500 / 503: временная ошибка, попробуйте еще раз.

Часто задаваемые вопросы#

Достаточно ли безопасна подпись HMAC?#

HMAC является важной основой, но также необходимы временная метка, nonce, идемпотентность, ротация ключей, TLS, минимальные привилегии и ведение журнала. Простое подписание не может предотвратить повтор и повторное выполнение.

Может ли Webhook напрямую изменять продукты или заказы?#

Не рекомендуется напрямую изменять данные высокого риска. Веб-перехватчики следует сначала записать в черновик, очередь проверки или поля с низким уровнем риска. Такие операции, как изменение цен, возврат средств и выдача купонов, требуют дополнительного одобрения.

Зачем мне нужен ключ идемпотентности?#

Вебхук или фоновую задачу можно повторить. Без ключа идемпотентности система может неоднократно отправлять электронные письма, неоднократно создавать коды скидок или неоднократно записывать контент обратно.

Источники#

• Рекомендации по безопасности OWASP Webhook, https://cheatsheetseries.owasp.org/
• Справочник по REST API WordPress, https://developer.wordpress.org/rest-api/
• Веб-API Adobe Commerce, https://developer.adobe.com/commerce/webapi/.