Vertrag der Artikelübertragung
Entwicklerreferenz zum Empfang vollständiger veröffentlichter Artikel.
Verwende pro Empfänger einen eigenen Signaturschlüssel. Schlüssel werden verschlüsselt gespeichert und nie in Verbindungsübersichten zurückgegeben. Die Signatur authentifiziert die Anfrage. Vertraue der Website-ID erst nach der Prüfung.
Anfrage und Prüfung
Structura sendet HTTPS POST mit Content-Type: application/json, X-Structura-Event-Id, X-Structura-Timestamp (Unix-Sekunden) und X-Structura-Signature (sha256= mit kleingeschriebenem Hex-Digest). Berechne HMAC-SHA256 über timestamp + "." + rawBody mit dem Schlüssel als UTF-8. Vergleiche gleich lange Digest-Bytes in konstanter Zeit. Weise Zeitstempel mit mehr als fünf Minuten Abweichung ab und parse erst dann JSON. Die Ereignis-ID im Header muss zum Body passen. Serialisiere geparstes JSON nicht zur Signaturprüfung erneut.
Nachrichtenformat
{
"schema_version": 1,
"event": "post.published",
"event_id": "article_<sha256>",
"delivered_at": "2026-09-28T10:00:00.000Z",
"site": {
"id": "site_123"
},
"post": {
"id": "post_123",
"slug": "first-article",
"title": "First article",
"html": "<p>Article body</p>",
"markdown": "Article body",
"excerpt": null,
"metaTitle": null,
"metaDescription": null,
"focusKeyword": null,
"locale": "en",
"publishedAt": "2026-09-28T10:00:00.000Z",
"updatedAt": "2026-09-28T10:00:00.000Z",
"canonicalUrl": "https://example.com/blog/first-article",
"featuredImage": null,
"author": null,
"jsonLd": []
}
}id ist bei Headless-Artikeln eine Zeichenfolge, bei WordPress eine Zahl. Fehlende Metadaten sind null; jsonLd ist ein Array. HTML ist bereinigt, Markdown entsteht aus demselben HTML. Die Inhaltssprache ist unabhängig von der Benachrichtigungssprache. Bilder bleiben an ihren angegebenen URLs gehostet. Autorenangaben erscheinen nur, wenn die Quelle eine öffentliche Identität liefert.
Bevor du jsonLd in ein <script type="application/ld+json">-Element einfügst, serialisiere es und ersetze jedes < durch \u003c. Gültiges JSON kann </script> enthalten; bereinigtes HTML macht dieses JSON nicht sicher für die direkte Einbettung.
Die vollständige Anfrage darf höchstens 1.000.000 UTF-8-Bytes enthalten, einschließlich HTML, Markdown, Metadaten und JSON-Escaping. Die Normalisierung erlaubt 995.904 Bytes für den Artikel und reserviert 4.096 Bytes für die Ereignishülle. Zu große Artikel werden mit article_too_large übersprungen; nutze dafür die Content API.
Speicherung und Übertragung
Erzwinge eine dauerhafte Eindeutigkeit von event_id. Aktualisiere in derselben Transaktion den Artikel anhand von site.id, post.id und post.locale und markiere das Ereignis als verarbeitet. Bestätige erst nach dem Commit. Gültige Duplikate erhalten 2xx ohne erneute Änderung. Vergleiche updatedAt, damit ältere Anfragen keine neuere Revision ersetzen. Die Ereignis-ID enthält Mandant, Website und Inhalt; eine erneut veröffentlichte Revision erhält eine neue ID.
Alle 2xx-Antworten gelten als Erfolg. Netzwerkfehler, HTTP 408, 429 und 5xx werden nach 150 ms einmal wiederholt. Andere Statuscodes scheitern sofort. Jeder Versuch hat 8 Sekunden Zeit. Antworttexte werden ignoriert. Es gibt keine spätere automatische Wiederholung. Weiterleitungen, private Adressen und Empfänger ohne HTTPS werden abgelehnt. Speichere zuerst und verlagere aufwendige Arbeit in deine eigene Warteschlange.
Nur die Veröffentlichung löst eine Übertragung aus. Spätere Änderungen und Löschungen erzeugen keine Ereignisse. Gleiche fehlende oder geänderte Artikel über die öffentliche Content API ab. WordPress benötigt ein Plugin mit dem optionalen Feld article. Ältere Plugins senden weiterhin andere Benachrichtigungen, aber keine vollständigen Artikel.