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. Lies den Schlüssel erst beim Bearbeiten einer Anfrage aus der Umgebung des Empfängers; speichere ihn nie in einer Datenbank und gib ihn nie über etwas preis, das der Browser aufrufen kann.
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": {
"url": "https://example.com/images/first-article.jpg",
"alt": "A short description of the image"
},
"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.
featuredImage ist null oder ein Objekt mit url und alt; nutze url für das Artikelbild und für og:image.
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.
Autor
post.author ist die reale Person, der die Website den Artikel zuschreibt, oder null, wenn die Quelle niemanden nennt. Es ist nie der Name einer Persona.
{
"name": "Jane Doe",
"bio": "Pastry chef and owner of a bakery in Leeds.",
"url": "https://example.com/about/jane-doe",
"avatarUrl": "https://example.com/images/jane-doe.jpg",
"sameAs": ["https://www.linkedin.com/in/jane-doe"]
}name ist immer gesetzt. bio, url (die Seite des Autors) und avatarUrl sind null, wenn sie fehlen. sameAs enthält bis zu 10 URLs weiterer Profile des Autors und kann leer sein. avatarUrl und sameAs sind additiv, schema_version bleibt daher 1; ignoriere unbekannte Schlüssel. WordPress-Quellen füllen ab Plugin 2.32.0 avatarUrl mit dem Profilbild und sameAs mit der Website aus dem WordPress-Profil des Nutzers. Bei älteren Plugins erhältst du avatarUrl: null und sameAs: [].
Bei Headless-Quellen ist jsonLd[0] ein BlogPosting-Knoten für den Artikel mit dem Autor als Person, derselbe Knoten, den die Content API liefert. Danach folgen die Einträge HowTo und FAQPage. WordPress-Quellen senden nur die Einträge HowTo und FAQPage. Gib jeden Eintrag so aus, wie er ankommt, den BlogPosting-Eintrag eingeschlossen; er nennt den Autor bereits als Person. Lass unseren nur dann weg, wenn deine Website für jeden Artikel ein eigenes BlogPosting erzeugt, damit eine Seite nie zwei trägt, und nimm die Autorenzeile in diesem Fall aus post.author.
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; nur eine Testübertragung zeigt dir die ersten 200 Zeichen. 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. Die Artikelübertragung wird für Headless-Websites im Kundenportal eingerichtet.
Testartikel
Beim Einrichten oder Bearbeiten einer Verbindung kann das Portal einen Testartikel senden. Er ist ein normales post.published-Ereignis mit derselben Signatur, ein korrekter Empfänger speichert ihn also. post.id und post.slug sind immer structura-test-article und post.locale ist en, daher aktualisieren wiederholte Tests denselben gespeicherten Artikel. Jeder Test hat eine neue event_id und ein späteres updatedAt. Du kannst den gespeicherten Testartikel jederzeit löschen. Eine Testübertragung macht einen Versuch mit derselben Frist von 8 Sekunden, und jede Empfänger-URL erlaubt fünf Tests in zehn Minuten.
Weiterführende Seiten
Zuletzt geprüft am