[Protocole révélé 1] Démantèlement du protocole de communication de base d'AI Ready : vérification de la charge utile de l'API et de la sécurité du Webhook

Réponse directe : le protocole AI Ready devrait élever les tâches d'IA d'une "invite" à des événements API gérables. Chaque demande doit contenir l'intention, la source, le contexte, les données, les contraintes et la clé d'idempotence ; Le Webhook doit disposer d'une protection par horodatage, nonce, signature et relecture.

À qui s’adresse cet article ?#

• Ingénieur de développement de base du système de e-commerce.

• Backend et architecte requis pour concevoir l'API de tâches d'IA.

• Équipe technique responsable de la sécurité des webhooks, des tentatives et de l'audit.

Pourquoi les tâches d'IA nécessitent-elles des protocoles de communication ?#

Si chaque plugin envoie une invite au modèle, il sera difficile pour le système de répondre aux questions suivantes :

• Qui a déclenché cette mission ?

• Quelles informations l'IA peut-elle lire ?

• L'IA peut-elle répondre ?

• Quelle langue et quel magasin sont utilisés pour la tâche ?

• Quel est le budget symbolique ?

• Est-il possible de réessayer après un échec ?

• Les webhooks en double entraîneront-ils des opérations en double ?

Le but du protocole AI Ready est de mettre ces informations de gestion dans chaque tâche, plutôt que d'être dispersées dans le code et les invites du programme.

Structure de base de la charge utile de la demande#

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

Chaque champ doit avoir une signification claire :

• event_id : identification unique de l'événement.

• idempotency_key : évite les opérations répétées causées par les tentatives.

• intent : type de tâche.

• source : plateforme source et magasin.

• context : langue, devise, opérateur et autorisations.

• data : les données nécessaires à la tâche.

• contraintes : restrictions de modèle et de réécriture.

Structure de base de la charge utile de réponse#

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

La réponse doit non seulement contenir du texte, mais également inclure le statut de vérification, les exigences de révision et l'utilisation du jeton.

Conception de signature Webhook#

En-tête suggéré :

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

Le contenu de la signature peut utiliser une chaîne canonique :

{timestamp}.{nonce}.{raw_body}

Ensuite, effectuez HMAC SHA-256 avec la clé partagée. L'extrémité réceptrice doit :

1. Vérifiez si l'horodatage se situe dans la fenêtre horaire autorisée.
2. Vérifiez si le nom occasionnel est utilisé.
3. Utilisez le corps brut pour recalculer la signature.
4. Vérifiez l'ID de l'événement et la clé d'idempotence.
5. Enregistrez le statut de traitement.

Codes d'état HTTP et tentatives#

• 200 / 204 : traité avec succès ou déjà traité.

• « 400 » : le format de la charge utile est incorrect et ne doit pas être réessayé.

• 401 / 403 : erreur de signature ou d'autorisation, ne doit pas être réessayée tant que les paramètres ne sont pas corrigés.

• 409 : conflit d'idempotence, une inspection manuelle est requise.

• 422 : la validation du schéma a échoué et ne doit pas être automatiquement réécrite.

• 429 : Limitation du débit, la nouvelle tentative peut être retardée.

• 500 / 503 : Erreur temporaire, vous pouvez réessayer.

##FAQ

Une signature HMAC est-elle suffisamment sécurisée ?#

HMAC est une base importante, mais l'horodatage, le nonce, l'idempotence, la rotation des clés, TLS, les moindres privilèges et la journalisation sont également nécessaires. La simple signature ne peut pas empêcher la relecture et l’exécution répétée.

Webhook peut-il modifier directement les produits ou les commandes ?#

Il n'est pas recommandé de modifier directement les données à haut risque. Les webhooks doivent d'abord être écrits dans des champs de brouillon, de file d'attente de révision ou à faible risque. Les opérations telles que les modifications de prix, les remboursements et l'émission de coupons nécessitent une approbation supplémentaire.

Pourquoi ai-je besoin d'une clé d'idempotence ?#

Le webhook ou la tâche en arrière-plan peuvent être réessayés. Sans clé d'idempotence, le système peut envoyer des e-mails à plusieurs reprises, créer des codes de réduction à plusieurs reprises ou réécrire du contenu à plusieurs reprises.

Références#

• Directives de sécurité des webhooks de l'OWASP, https://cheatsheetseries.owasp.org/
• Manuel de l'API WordPress REST, https://developer.wordpress.org/rest-api/
• API Web Adobe Commerce, https://developer.adobe.com/commerce/webapi/