A webhook receiver needs to distinguish a field that is missing from one that is present with null or an empty string. It also needs to accept different article payloads for manual publishing, scheduled publishing and Sync. Use the field map below to design validation and storage, then confirm your project’s actual delivery shape before enabling writes.
The core article payload includes structured ctas. The optional author field depends on whether a byline has been configured or explicitly cleared. Confirm that your receiver supports those mappings before enabling them.
Article fields that differ by delivery path
| Field group | Manual publish or republish | Scheduled publish | Sync |
|---|
| Event | blog.published for a new external post; blog.updated when an external post ID exists | The same external-ID distinction | blog.updated |
|---|
| Core article fields | Included | Included | Included |
|---|
excerpt_short, published_at, images | Included | Included | Not included |
|---|
idempotency_key, publish_attempt | Not included | Included | Not included |
|---|
jsonld | Not included | Included | Not included |
|---|
“Included” describes key presence, not a promise that the value is non-null. A sample publish has a preview- blog ID and illustrates article parsing; it does not exercise scheduled retry fields, generated JSON-LD or every update path. test.ping is a connection event, so do not require article fields to process it.
Core article fields for publishing and Sync
| Field | Value to handle | Receiver mapping |
|---|
event | Event-name string | Route publication and update events separately from connection, unpublish and delete events. |
|---|
blog_id | theStacc article identifier | Use it to associate updates with your stored article. Treat preview-prefixed sample IDs separately from real records. |
|---|
title, slug | Article title and slug values | Validate the values required by your CMS. Do not use a mutable slug as the only article identity. |
|---|
content | Prepared HTML body | Apply your site’s HTML policy and storage requirements. Validate a usable body rather than treating key presence as sufficient. |
|---|
excerpt | Reader-facing summary, empty string or null | An explicit empty excerpt stays empty. A null excerpt falls back to the meta description; when both are null, the result is null. Recognized planning-brief text is replaced with a reader-facing summary before this fallback. |
|---|
meta_title | Meta-title value, falling back to the article title when the meta title is empty or null | Map to the site’s SEO-title field. Validate the resulting value for your destination. |
|---|
meta_description | Description value, which can be null | Define how your site handles an absent description instead of rejecting every nullable value. |
|---|
featured_image_url, featured_image_alt | Featured-image URL and companion alt-text value | Map the hero separately from body images. Do not assume a particular CDN hostname or that an image is present. |
|---|
categories, tags | Stored values, usually arrays; scheduled publishing falls back to empty arrays | Manual and Sync constructors can preserve an explicit null. Normalize or reject according to your documented destination policy. |
|---|
keyword | Focus-keyword value or null | Treat it as metadata; it is not a required article identity or byline. |
|---|
ctas | List of resource links with label, url and type; empty when suppressed or no links are resolved | Choose either the prepared HTML resources section or your own structured-link rendering to avoid displaying the resources twice. |
|---|
author | Optional object with name, type and optional id, or null | Apply the byline mapping below. An omitted author is different from an explicit reset. |
|---|
excerpt_short uses the reader-facing excerpt, then the meta description, then an empty string. It trims surrounding whitespace and limits the result to 256 characters, including a trailing ellipsis when truncation is needed. It prefers a word boundary when one is sufficiently far into the text, but can cut a long unbroken value. Because an empty excerpt triggers its fallback, excerpt_short is not always a truncated copy of excerpt.
Where present, published_at is a UTC publish-time value produced with an ISO-format timestamp. Accept an explicit UTC offset such as +00:00; do not require a literal Z suffix. On an update, decide whether this delivery timestamp belongs in a modification field. Do not overwrite the original publication date just because a publish or republish delivery contains a new timestamp. Sync does not supply this field in the path described here.
Set limits from your CMS and receiver schema instead of treating typical content lengths as hard caps. Reject an unsupported value with a useful error, or document an intentional normalization policy rather than silently truncating it.
The body preparation removes the first inline image matching the featured-image URL, allowing a query string or fragment on that URL. It leaves the body unchanged if no match exists or no featured-image URL is supplied. Consequently, do not rely on a blanket guarantee that the hero can never appear in the body.
When supplied, images lists quoted src values extracted from the prepared body, in document order, deduplicated by the exact URL string. It does not extract lazy-loading data-src values. An absent alt attribute produces an empty alt string. Render or mirror the images your site needs using the self-hosting images guide; keep featured-image handling separate.
Scheduled publishing adds idempotency_key and publish_attempt. The scheduled key described here combines the blog ID with the stored external post ID, or new before an external ID exists. Repeated updates to the same external ID can share a key, so it is not a unique identifier for every separate edit. Define retry deduplication without suppressing legitimate later updates; see idempotency and retries.
Blog author
Manual publishing, scheduled publishing and Sync include the configured optional author. When no explicit author setting exists, the field is omitted. Saving a website-default reset sends author: null; a valid explicit selection sends its name and Person or Organization type, plus an ID when selected from the site directory. Your receiver must implement the corresponding byline update.
This illustrative author fragment represents an organization byline:
Receiver mapping for the optional author field
| Incoming value | Recommended behavior |
|---|
author omitted | Preserve the existing byline on updates; use the site’s default on creation. |
|---|
author: {name, type} | Validate and store the explicit name and supported type. |
|---|
author: null | Clear the explicit selection and apply the documented site default. |
|---|
Check property presence rather than truthiness so a deliberate null reset is handled. Author saves require a nonblank name of up to 200 characters and a Person or Organization type. A directory ID is optional; validate it against your own author records before assigning a byline.
Website receiver checklist
- Validate the event before validating article fields. Handle a connection test without inserting an article.
- Upsert publication and update events using the article identity, with a documented policy for missing, null and empty values.
- If optional author support is confirmed, map its ID or name into the site’s byline model. Define what happens when an ID no longer exists.
- Render stored names as escaped text and keep visible bylines, listing cards and article structured data consistent.
- Refresh the relevant page or build caches after a successful update. Verify the public page instead of treating a delivery acknowledgement as proof of rendering.
- Test your handler locally with new, updated, missing-field, null-field and repeated-delivery fixtures. Keep the authentication and deduplication policies appropriate to your integration.
Scheduled payloads include generated jsonld, while the manual publishing and Sync paths described here omit it. An explicit author supplies the scheduled BlogPosting author name and Person or Organization type. Without an explicit author, the graph falls back to an Organization using project or website naming before the blog author and finally Editorial Team. Maintain the site’s visible byline and structured data from the same stored record on every update.
Select existing site authors
Configure an optional author directory using Author-list URL in Custom Webhook settings. In the blog author form, selecting an Existing website author fills a draft; Save author stores the selection. Saving alone does not update the public website. The existing website authors guide covers directory limits, selection and receiver responsibilities.
The ctas list is also rendered into the prepared HTML resources section, identified by class="fairview-cta-resources", before the locked footer. If you render structured links separately, remove only that resources section rather than unrelated footer content. A successful response alone does not prove that your mapping was applied; use the response contract when designing acknowledgements.