> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/publishing-caching-and-webhooks.md).

# Publishing, caching and webhooks

The storefront caches what it reads from the CMS. A publish should reach shoppers in seconds, not when the cache expires.

The storefront caches what it reads from the CMS. A publish should reach shoppers in seconds, not when the cache expires — so something has to tell the storefront. On Emporix that something is the **Emporix Orchestration Engine**.

## How the storefront caches

Reads are cached for up to an hour and tagged, so a refresh can target exactly what changed:

| Tag                                     | Covers                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| `cms:site:{site}`                       | everything of a site — the coarse tag a layout, theme or component publish uses |
| `cms:page:{site}:{locale}:{url}`        | one page (`url` with a leading slash, `/` for the home page)                    |
| `cms:layout:{site}:{locale}:{layoutId}` | one layout                                                                      |
| `cms:theme:{site}`                      | the site's theme                                                                |

{% hint style="info" %}
The cache period is the backstop: if a refresh call is lost, the page still updates within the hour.
{% endhint %}

## The refresh endpoint

The plugin mounts `POST /api/cms/revalidate`:

```
POST https://your-storefront/api/cms/revalidate
Authorization: Bearer <CMS_REVALIDATE_SECRET>
Content-Type: application/json

{ "tags": ["cms:site:main"], "paths": ["/"] }
```

* The secret may also be sent as `X-CMS-Revalidate-Secret`.
* Send `tags`, `paths` or both; at most 100 of each.
* Responses: `200 { revalidated, tags, paths }`; `401` for a missing or wrong secret; `400` for invalid JSON or nothing to refresh; `503` when `CMS_REVALIDATE_SECRET` is not set — the endpoint is off rather than open.

The route is exempt from the storefront's CSRF check, because it authenticates with its own secret.

## Calling it from Emporix: the Orchestration Engine

On Emporix, cms-api does not deliver webhooks itself. Every change the CMS makes is already a change to its Emporix custom entities, and the **Orchestration Engine** can react to those directly — call the refresh endpoint above, or any other system, with whatever authentication it supports. Nothing is configured in the CMS; its **Settings** → **Webhooks** tab says so instead of showing a form.

The custom entity types are `STOREFRONT_CMS_PAGE`, `STOREFRONT_CMS_LAYOUT`, `STOREFRONT_CMS_THEME` and `STOREFRONT_CMS_COMPONENT`. Each entity has up to three kinds of instance:

| Instance id            | What it is                                                                   |
| ---------------------- | ---------------------------------------------------------------------------- |
| `<baseId>-draft`       | The draft. Approval state lives here, in the data mixin's `approval_status`. |
| `<baseId>`             | The live version.                                                            |
| `<baseId>-<timestamp>` | An archived version.                                                         |

The CMS events map onto instance changes:

| CMS event               | Custom-entity signal                                                                                                                                                                   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`               | A `-draft` instance is created for a `baseId` that has no live instance.                                                                                                               |
| `updated`               | A `-draft` instance is updated, and `approval_status` did not change.                                                                                                                  |
| `submitted`             | A `-draft` instance's `approval_status` becomes `pending`.                                                                                                                             |
| `withdrawn`             | `approval_status` goes from `pending` to `open`.                                                                                                                                       |
| `approved` / `rejected` | `approval_status` becomes `approved` / `rejected` (`rejection_reason` alongside).                                                                                                      |
| `published`             | A `<baseId>` instance is created with `version: live`. In the same operation the previous live version becomes a `<baseId>-<timestamp>` instance and the `-draft` instance is deleted. |
| `restored`              | A `<baseId>` instance is created from an archived version, while no `-draft` deletion is involved.                                                                                     |
| `deleted`               | The `<baseId>` or `-draft` instance is deleted **outside** a publish.                                                                                                                  |

**For a fresh storefront after a publish,** trigger on a `<baseId>` instance being created with `version: live`, and call the refresh endpoint with `cms:site:{site}` — the coarse tag covers pages, layouts and the theme alike. Refreshing a single page by its `cms:page:…` tag is finer, if your rule can build the tag from the entity.

{% hint style="warning" %}
Two cautions for building rules:

* **Publishing deletes instances.** The draft is removed and the old live version is replaced. A rule that treats every deletion as `deleted` fires on every publish. Key `deleted` on "no `<baseId>` instance exists afterwards" rather than on the deletion alone.
* **The payload is the entity**, not a CMS event envelope. Build the request in the Orchestration Engine; you receive the content itself.
  {% endhint %}

If a deployment sets `CMS_EMPORIX_NAMESPACE`, the type names carry that prefix (`INTEGRATION_STOREFRONT_CMS_PAGE`).

Next: [Switching between Storyblok and Contenter](https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/switching-storyblok-contenter.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/partner-library/partner-components/medienwerft-cms/developer-guide/publishing-caching-and-webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
