Skip to Content
ReferenceArticle delivery contract

Article delivery contract

Developer reference for receiving complete published articles.

Configure a separate signing secret for each receiver. Secrets stay in encrypted connection storage and are never returned in connection summaries. Treat the signature as authentication; do not trust a site ID before verifying it. Read the secret from the receiver’s environment at request time; never store it in a database or expose it through anything the browser can call.

Request and verification

Structura sends HTTPS POST with Content-Type: application/json, X-Structura-Event-Id, X-Structura-Timestamp (Unix seconds) and X-Structura-Signature (sha256= followed by a lowercase hex digest). Compute HMAC-SHA256 over timestamp + "." + rawBody using the secret as UTF-8. Compare equal-length digest bytes in constant time, reject timestamps more than five minutes from your clock, then parse JSON. Validate the header event ID matches the body. Do not stringify parsed JSON for verification.

Payload

{ "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 is a string for headless posts or a number for WordPress posts. Optional metadata is null; jsonLd is an array. HTML is sanitized and Markdown is generated from that HTML. Content locale is independent of the notification language. Images remain hosted at their supplied URLs. Author details appear only when the source supplies a public identity.

featuredImage is null or an object with url and alt; use url for the article image and og:image.

Before inlining jsonLd inside a <script type="application/ld+json"> element, serialize it and escape every < as \u003c. A valid JSON value can contain </script>; HTML sanitization does not make that JSON safe to inline.

The complete request is limited to 1,000,000 UTF-8 bytes, including HTML, Markdown, metadata and JSON escaping. Normalization allows 995,904 bytes for the article and reserves 4,096 bytes for the event envelope. Oversized articles are skipped with article_too_large; use the Content API for larger content.

Author

post.author is the real person the site credits for the article, or null when the source credits nobody. It is never a persona name.

{ "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 is always set. bio, url (the author’s page) and avatarUrl are null when missing. sameAs lists up to 10 of the author’s other profile URLs and can be empty. avatarUrl and sameAs are additive, so schema_version stays 1; ignore keys you don’t know. WordPress sources fill avatarUrl from the user’s profile picture and sameAs from the website in their WordPress profile, starting with plugin 2.32.0. From older plugins you receive avatarUrl: null and sameAs: [].

For headless sources, jsonLd[0] is a BlogPosting node for the article with the author as a Person, the same node the Content API serves. HowTo and FAQPage entries follow it. WordPress sources send only the HowTo and FAQPage entries. Emit every entry as it arrives, the BlogPosting included; it already names the author as a Person. Skip ours only when your site generates its own BlogPosting for every article, so a page never carries two, and take the byline from post.author in that case.

Storage and delivery semantics

Use a durable unique constraint on event_id. In the same transaction, upsert by site.id, post.id and post.locale, and record the event as processed. Acknowledge only after commit. A duplicate valid event returns 2xx without reapplying it. Compare updatedAt to avoid replacing a newer stored revision with an older request. Event IDs include tenant/site/content identity, so a republished revision has a new ID.

All 2xx responses succeed. Network errors, HTTP 408, 429 and 5xx get one retry after 150 ms. Other statuses fail immediately. Each attempt has a 8-second deadline; response bodies are ignored, except that a test send shows you the first 200 characters. There is no later automatic replay. Redirects, private network addresses and non-HTTPS receivers are rejected. Keep processing fast: persist first, then queue any expensive work yourself.

Only publication triggers delivery. Subsequent edits/deletions do not emit events. Reconcile missed publications or updates using the public Content API. Article delivery is set up for headless sites in the customer portal.

Test articles

While you set up or edit a connection, the portal can send a test article. It is a normal post.published event, signed like any other, so a correct receiver stores it. post.id and post.slug are always structura-test-article and post.locale is en, so repeated tests update one stored article. Each test has a new event_id and a later updatedAt. Delete the stored test article whenever you like. A test send makes one attempt with the same 8-second deadline, and each receiver URL allows five tests every ten minutes.

Last verified