Keep a Permanent Publish History

View as Markdown
Last updated November 11, 2026

Teams with compliance or audit requirements need to show, for every version of an entry or asset, when it was published, how long it stayed live, and when it was unpublished. Contentstack shows publish activity in the Publish Queue for the last 30 days, and returns it through the API for up to 90 days. To keep that history for as long as you need, copy it to storage you control.

There are two ways to do this:

Neither the Publish Queue nor the exported logs store how long a version was live. Each publish and each unpublish is a separate record, so you work out the live periods from those records, as described in Work Out How Long Each Version Was Live.

Diagram Walkthrough

The following diagram shows both options. Contentstack records each publish and unpublish in the Publish Queue. With Log Targets, Contentstack exports those records to your cloud storage every hour. With webhooks, Contentstack sends each event to a receiver you build, which stores it. Either way, your reports read the live periods of each version from the stored records.

Click to enlarge

Choose an Option

The Publish Queue lists every publish, unpublish, and delete action on entries and assets, along with release deployments, including the version, language, environment, user, and time. The app shows the last 30 days, and the Get publish queue API request returns up to 90 days. Publish and unpublish actions are recorded in the Publish Queue, not in the Audit Log.

Use the following comparison to choose how to keep these records:

ConsiderationLog TargetsWebhooks
SetupConfigured in Administration, with no codeA receiver and a data store that you build and run
Who sets it upAn organization Owner or AdminA user who can create webhooks in the stack
DeliveryExported every hourSent as each item is published or unpublished
DestinationAWS S3, Azure Blob Storage, or Google Cloud StorageAny HTTPS endpoint and any data store
ScopePublish logs for every stack and branch in your organizationOne stack and one branch per webhook
Missed recordsIf an export fails, the next run includes its recordsFailed deliveries are not resent, so you check your records against the Publish Queue

Use Log Targets unless you need events as they happen, a destination other than the supported cloud storage providers, or a history scoped to specific stacks or branches.

Export Publish Logs With Log Targets

Log Targets export the publish logs of every stack and branch in your organization to your own cloud storage every hour. Each exported record is the same document that the Get publish queue API request returns, including the item, version, language, environment, action, user, and time. You keep the exported files for as long as your compliance requirements need.

Prerequisites

  • Owner or Admin permissions in your organization
  • Log Targets must be enabled for your organization
  • An AWS S3 bucket, Azure Blob Storage container, or Google Cloud Storage bucket that Contentstack can write to

Steps to Export Publish Logs

  1. In Administration, open Log Targets.
  2. In the Destinations tab, click Add Cloud Destination, enter your cloud storage details, and click Create Configuration.
  3. In the Schedules tab, click Create Schedule.
  4. Select the destination you created as the Cloud Configuration, select Published as the Data Type, and enter a Base Path, such as contentstack-published-logs.
  5. Turn on Activate Schedule, and click Create Schedule.

The first export runs about one hour after you create the schedule, and then every hour. Exports start from the time you activate the schedule: earlier publish activity is not exported and stays available only in the Publish Queue, for up to 90 days through the API. Activate the schedule before you need the history.

Check the History tab regularly: each export shows its status, the number of records, and the time window it covers. If an export fails, the next run includes the records from the failed window. For details on each field, see Log Targets.

To report how long each version was live, read the exported records and follow Work Out How Long Each Version Was Live.

Record Publish Events With Webhooks

Use webhooks when you need each event as it happens, want to store the history somewhere other than the supported cloud storage providers, or cannot use Log Targets.

Prerequisites

  • A Contentstack account with permission to create webhooks in the stack
  • A management token for the stack, to read the Publish Queue when you fill gaps
  • An HTTPS endpoint that Contentstack can reach, such as a serverless function or a small web service
  • A durable data store for the history, such as a relational database or an object store
  • Node.js 20 or later, to run the sample code in this guide

Step 1: Build the Receiver

The receiver verifies that each request came from Contentstack, stores the event, and then responds with a 2XX status code. Respond only after the event is stored: if your endpoint returns any other status code or does not respond within 30 seconds, Contentstack retries the request according to the webhook retry policy.

Store one record per event, with these fields:

  • module: entry or asset
  • uid: The unique ID of the entry or asset
  • version: The version that was published
  • locale: The language code
  • environment: The unique ID of the environment
  • action: publish or unpublish
  • status: success or fail
  • user: The unique ID of the user who published the item, from publish_details (publish events only)
  • source: The release name and unique ID, when the item was deployed as part of a release
  • time: The time Contentstack triggered the event
  • payload: The complete request body, so you can answer questions later that these fields do not cover

Note In an unpublish event, the payload carries the item's latest saved version, which is not necessarily the version that was live. Read the unpublished version from the live period that the unpublish ends.

Keep the store append-only: never update or delete a record. An append-only log is what auditors expect, and it lets you rebuild any report from the raw events.

The following Node.js sample uses Express. It verifies the request signature against the raw request body, as described in Secure Your Webhooks, and passes each record to a saveRecord function that you connect to your data store.

const express = require('express');
const crypto = require('crypto');
const fs = require('fs');

// Contentstack's signing public key, saved from the /.well-known/public-keys.json
// endpoint on your region's host (see Secure Your Webhooks).
const PUBLIC_KEY = crypto.createPublicKey(fs.readFileSync('public.key', 'utf8'));

const app = express();

// Keep the raw body: the signature is calculated over the exact bytes sent.
app.post('/publish-history', express.raw({ type: 'application/json' }), async (req, res) => {
  const header = req.get('X-Contentstack-Request-Signature') || '';
  const signature = header.split(',')[0].split('=')[1] || '';

  const isVerified = crypto.verify(
    'sha256',
    req.body,
    { key: PUBLIC_KEY, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 },
    Buffer.from(signature, 'base64')
  );
  if (!isVerified) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  const item = event.data[event.module] || {};

  const record = {
    // The same delivery can arrive more than once, so derive the ID from its content.
    id: crypto.createHash('sha256').update(req.body).digest('hex'),
    module: event.module,
    uid: item.uid,
    version: item._version,
    locale: event.data.locale || item.locale,
    environment: event.data.environment ? event.data.environment.uid : null,
    action: event.data.action || event.event,
    status: event.data.status,
    user: item.publish_details ? item.publish_details.user : null,
    source: event.source || null,
    time: event.triggered_at,
    payload: event,
  };

  try {
    await saveRecord(record); // Write to your data store. Ignore a record whose id already exists.
    res.status(200).end();
  } catch (err) {
    console.error(err);
    res.status(500).end(); // Contentstack retries the delivery.
  }
});

app.listen(3000);

Note A retried delivery carries the same body as the first attempt, so a record ID derived from the body lets your store ignore duplicates.

Step 2: Create the Webhook

Create a webhook in your stack with the following settings:

  • URL to Notify: The URL of your receiver
  • Authentication Method: The method your receiver accepts, such as Basic Auth with a username and password you use nowhere else, so your receiver can check the credentials as well as the signature
  • Request Signing Method: Default (Contentstack Certificate), which the sample code verifies using Contentstack's public key
  • Send Concise Payload: Turned off, so that each stored payload holds the full entry or asset details
  • Channels: The publish events for entries and assets:
    • content_types.entries.publish
    • content_types.entries.unpublish
    • assets.publish
    • assets.unpublish
    • Optionally, content_types.entries.publish.fail, content_types.entries.unpublish.fail, assets.publish.fail, and assets.unpublish.fail, to record failed attempts as well

If you select HMAC Signing instead, verify the X-Contentstack-HMAC-Signature header with your organization's shared secret key, as described in HMAC Signing.

These events fire once for each item, including items published in a bulk action or deployed in a release. An item deployed in a release carries a source key with the release's name and unique ID. For the full list of events, see Webhook Events.

A webhook applies to one branch, selected under Branch-level Scope. If you publish from more than one branch, create a webhook for each branch whose history you need.

Step 3: Fill Gaps from the Publish Queue

A webhook delivery can fail: your endpoint might be down for longer than the retries last, or the Webhook Circuit Breaker might disable a webhook that fails repeatedly. Events that are not delivered are not sent again automatically, so check your history against the Publish Queue on a schedule, well within the 90 days that the API returns:

  1. Read recent activity with the Get publish queue API request, using your management token.
  2. For each publish or unpublish item in the response, look for a matching record in your store with the same item, locale, environment, and action at about the same time. Do not match unpublish records on version, because an unpublish event carries the item's latest version.
  3. Add a record for any item that has no match, and mark it as recovered from the Publish Queue so your reports show where it came from.

Also check the webhook logs and the webhook's status regularly, and re-enable an unhealthy webhook once your endpoint is available again.

Work Out How Long Each Version Was Live

Contentstack records a publish and an unpublish as separate records and does not store how long a version was live. Whichever option you use, work out the live periods from the stored records. Each record needs the item, version, language, environment, action, status, and time.

To report how long a version was live, group the successful records by item, language, and environment, sort each group by time, and read it as a timeline:

  • A publish starts a live period for that version.
  • The live period ends at the next publish in the same group, because publishing a newer version replaces the older one, or at the next unpublish.
  • A live period with no later record is still live.

Publishing a newer version does not create an unpublish record for the version it replaces, so always close a live period at the next publish, not only at an unpublish.

The following function builds the live periods from records with the fields described in Step 1 of Record Publish Events With Webhooks. For Log Targets exports, convert each exported document first, as shown after the function.

function livePeriods(records) {
  const groups = new Map();
  for (const r of records.filter((r) => r.status === 'success')) {
    const key = [r.module, r.uid, r.locale, r.environment].join('|');
    if (!groups.has(key)) groups.set(key, []);
    groups.get(key).push(r);
  }

  const periods = [];
  for (const group of groups.values()) {
    group.sort((a, b) => a.time.localeCompare(b.time));
    let open = null;
    for (const r of group) {
      if (open) {
        open.unpublished_at = r.time;
        periods.push(open);
        open = null;
      }
      if (r.action === 'publish') {
        open = {
          module: r.module,
          uid: r.uid,
          version: r.version,
          locale: r.locale,
          environment: r.environment,
          published_at: r.time,
          unpublished_at: null,
        };
      }
    }
    if (open) periods.push(open);
  }
  return periods;
}

Each period gives the version, when it was published, and when it stopped being live. A period whose unpublished_at is null is the version live today.

An exported publish log document lists its environments and languages as arrays, and holds both entries and assets under the entry key, with type set to entry or asset. The following function turns one document into one record for each environment and language:

function fromPublishLog(doc) {
  const records = [];
  for (const environment of doc.environment || []) {
    for (const locale of doc.locale || []) {
      records.push({
        module: doc.type,
        uid: doc.entry.uid,
        version: doc.entry.version,
        locale,
        environment,
        action: doc.action,
        status: doc.publish_details ? doc.publish_details.status : null,
        time: doc.published_at,
      });
    }
  }
  return records;
}

Pass the converted records to livePeriods, for example livePeriods(docs.flatMap(fromPublishLog)). Records with a status other than success, such as skipped when an item was already published, do not change a live period.

Additional Resource To create backups of your content as well as its publish history, see Back up Existing Content.