[Offenbartes Protokoll 1] Demontage des Kernkommunikationsprotokolls von AI Ready: API Payload und Webhook-Sicherheitsüberprüfung

Direkte Antwort: Das AI-Ready-Protokoll sollte KI-Aufgaben von einer „Eingabeaufforderung“ zu verwaltbaren API-Ereignissen machen. Jede Anfrage muss Absicht, Quelle, Kontext, Daten, Einschränkungen und Idempotenzschlüssel enthalten. Der Webhook muss über Zeitstempel, Nonce, Signatur und Wiedergabeschutz verfügen.

Für wen ist dieser Artikel relevant?#

• Kernentwicklungsingenieur für E-Commerce-Systeme.

• Backend und Architekt erforderlich, um die KI-Aufgaben-API zu entwerfen.

• Technisches Team, verantwortlich für Webhook-Sicherheit, Wiederholungsversuche und Auditing.

Warum erfordern KI-Aufgaben Kommunikationsprotokolle?#

Wenn jedes Plug-In eine Eingabeaufforderung an das Modell sendet, ist es für das System schwierig, die folgenden Fragen zu beantworten:

• Wer hat diese Mission ausgelöst?

• Welche Informationen kann KI lesen?

• Kann KI zurückschreiben?

• Welche Sprache und welcher Speicher werden für die Aufgabe verwendet?

• Wie hoch ist das Token-Budget?

• Ist es möglich, es nach einem Misserfolg noch einmal zu versuchen?

• Verursachen doppelte Webhooks doppelte Vorgänge?

Der Zweck des AI-Ready-Protokolls besteht darin, diese Verwaltungsinformationen in jede Aufgabe zu integrieren, anstatt sie im Programmcode und in den Eingabeaufforderungen zu verstreuen.

Grundstruktur der Anforderungsnutzlast#

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

Jedes Feld sollte eine klare Bedeutung haben:

• „event_id“: eindeutige Identifikation des Ereignisses.

• „idempotency_key“: Vermeiden Sie wiederholte Vorgänge, die durch Wiederholungsversuche verursacht werden.

• „Absicht“: Aufgabentyp.

• „Quelle“: Quellplattform und -speicher.

• „Kontext“: Sprache, Währung, Betreiber und Berechtigungen.

• „Daten“: die für die Aufgabe erforderlichen Daten.

• „Einschränkungen“: Modell- und Rückschreibeinschränkungen.

Grundstruktur der Antwortnutzlast#

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

Die Antwort sollte nicht nur Text enthalten, sondern auch den Verifizierungsstatus, die Überprüfungsanforderungen und die Token-Nutzung enthalten.

Webhook-Signaturdesign#

Vorgeschlagener 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

Der Signaturinhalt kann eine kanonische Zeichenfolge verwenden:

{timestamp}.{nonce}.{raw_body}

Führen Sie dann HMAC SHA-256 mit dem gemeinsamen Schlüssel aus. Die Empfängerseite sollte:

1. Prüfen Sie, ob der Zeitstempel innerhalb des zulässigen Zeitfensters liegt.
2. Prüfen Sie, ob die Nonce verwendet wird.
3. Verwenden Sie den Rohtext, um die Signatur neu zu berechnen.
4. Überprüfen Sie die Ereignis-ID und den Idempotenzschlüssel.
5. Speichern Sie den Bearbeitungsstatus.

HTTP-Statuscodes und Wiederholungsversuche#

• „200“ / „204“: Erfolgreich verarbeitet oder bereits verarbeitet.

• „400“: Das Nutzlastformat ist falsch und sollte nicht erneut versucht werden.

• „401“ / „403“: Signatur- oder Berechtigungsfehler, sollte nicht erneut versucht werden, bis die Einstellungen korrigiert wurden.

• „409“: Idempotenzkonflikt, menschliche Prüfung ist erforderlich.

• „422“: Schemavalidierung ist fehlgeschlagen und sollte nicht automatisch zurückgeschrieben werden.

• „429“: Ratenbegrenzung, Wiederholungsversuche können verzögert werden.

• „500“ / „503“: Vorübergehender Fehler, Sie können es erneut versuchen.

FAQ#

Ist eine HMAC-Signatur sicher genug?#

HMAC ist eine wichtige Grundlage, aber auch Zeitstempel, Nonce, Idempotenz, Schlüsselrotation, TLS, geringste Privilegien und Protokollierung sind erforderlich. Das bloße Signieren kann die Wiederholung und wiederholte Ausführung nicht verhindern.

Kann Webhook Produkte oder Bestellungen direkt ändern?#

Es wird nicht empfohlen, Hochrisikodaten direkt zu ändern. Webhooks sollten zuerst in Entwürfe, Überprüfungswarteschlangen oder Felder mit geringem Risiko geschrieben werden. Vorgänge wie Preisänderungen, Rückerstattungen und die Ausstellung von Gutscheinen erfordern eine zusätzliche Genehmigung.

Warum benötige ich einen Idempotenzschlüssel?#

Der Webhook oder die Hintergrundaufgabe kann erneut versucht werden. Ohne einen Idempotenzschlüssel sendet das System möglicherweise wiederholt E-Mails, erstellt wiederholt Rabattcodes oder schreibt Inhalte wiederholt zurück.

Quellen#

• OWASP Webhook-Sicherheitsrichtlinien, https://cheatsheetseries.owasp.org/
• WordPress REST API-Handbuch, https://developer.wordpress.org/rest-api/
• Adobe Commerce-Web-APIs, https://developer.adobe.com/commerce/webapi/