How to Back Up and Restore Uniform Projects (Webhooks + CLI)

Backing up your Uniform project helps you recover from accidental deletions, unintended bulk changes, content corruption, or broader incidents. This article explains two complementary strategies:

• Incremental backups via Webhooks (near real-time, event-driven)

• Full snapshot backups via Uniform CLI (scheduled or on-demand exports)

Most teams use both: webhooks for “every change” + CLI snapshots for “known-good restore points”.

Choose the Right Backup Method

Prerequisites

For Webhook Backups

• Ability to deploy an HTTPS endpoint (API route, serverless function, etc.)

• Access to your Uniform Webhook signing secret (to verify authenticity)

• A Uniform API key (or equivalent credentials) that can read the entities you want to back up

• A storage destination (Git repo, S3/Azure/GCS, database, etc.)

For CLI Snapshots

• Node.js + npm

• Uniform CLI installed (see official CLI docs)

• Uniform credentials configured for the CLI (API key/project selection as required by your setup)

• A secure place to store exported files (private Git repo or encrypted object storage)

Strategy 1: Automated Incremental Backups via Uniform Webhooks

Uniform webhooks send an HTTP POST to your endpoint when events occur (e.g., composition changes). For backups, your goal is to capture enough information to reconstruct content later.

Recommended Event Subscriptions (Default)

Start with the core content events:

• composition.changed, composition.published, composition.deleted

• entry.changed, entry.published, entry.deleted

Add these if your project uses them:

• Releases: composition.release.*, entry.release.*

• Project Map: projectmap.update, projectmap.node.*, projectmap.delete

• Redirects: redirect.insert, redirect.update, redirect.delete

• Personalization manifest (if used): manifest.published

Keep the subscription list minimal at first. You can expand later.

Step 1 — Create the Webhook Endpoint in Uniform

1. In your Uniform project, go to Settings → Webhooks.

2. Create a new webhook endpoint and enter your receiver URL (HTTPS).

3. Select the event types listed above.

4. Save.

Step 2 — Implement a Secure Webhook Receiver

Your receiver should do four things:

1. Verify the webhook signature (prevents spoofed requests)

2. Store the raw webhook payload (audit + reprocessing)

3. Fetch the full entity JSON (when needed) using Uniform APIs

4. Store a versioned backup of that entity

Operational requirements (don’t skip)

• Idempotency / dedupe: webhook deliveries can be repeated. Use the event ID as a dedupe key.

• Out-of-order events: don’t assume arrival order. Store timestamps/state info and keep the latest version.

• Retries & dead-letter handling: if your storage/API call fails, queue the job and retry with backoff.

• Rate limiting: fetching full entity JSON for every event can spike. Add throttling and batching where needed.

Step 3 — Fetch Full Content for “Changed/Published” Events

Webhook payloads often contain identifiers plus an api_url, not the full content object. Your backup process should generally:

• For *.changed or *.published:

  • Call api_url (authenticated) to retrieve the full JSON representation

  • Save it to your backup store

• For *.deleted:

  • The entity may no longer be retrievable via API

  • Mark it as deleted in your backup store (but keep the last known JSON captured earlier)

Example storage layout (Git-friendly):

uniform-backups/
  events/raw/2026-01-06/<event-id>.json
  compositions/<composition-id>/<timestamp>.json
  entries/<entry-id>/<timestamp>.json
  projectmap/<timestamp>.json
  redirects/<timestamp>.json

Step 4 — Verify Webhook Backups

• Trigger a safe change (edit a test composition).

• Confirm:

  • Uniform shows successful delivery in webhook logs

  • Your receiver stored the raw event

  • Your receiver stored the fetched entity JSON

• Test a failure scenario (temporarily disable storage) and confirm retries/alerts work.

Strategy 2: Full Backup & Restore via the Uniform CLI

CLI exports provide a consistent snapshot of your project at a point in time and are ideal for scheduled backups and disaster recovery.

Step 1 — Install the CLI

Install the Uniform CLI using the official installation instructions (commonly via npm).

Keep the CLI version pinned in CI (or document the tested version) to avoid unexpected behavior changes.

Step 2 — Create a Backup Config File

Create a uniform.config.json (or uniform.config.ts) that defines:

• output format (JSON/YAML)

• output directory

• which entities to export

Example (JSON):

{
  "serialization": {
    "format": "json",
    "mode": "mirror",
    "directory": "./uniform-backup",
    "entitiesConfig": {
      "composition": {},
      "component": {},
      "entry": {},
      "contentType": {},
      "projectMapDefinition": {},
      "projectMapNode": {},
      "redirect": {},
      "workflow": {}
    }
  }
}

Notes:

• mode: "mirror" is appropriate for snapshot backups because it represents the full state.

• Add/remove entities based on what your project actually uses (e.g., personalization/testing entities if applicable).

Step 3 — Run a Snapshot Backup (Export)

From the directory containing your config:

uniform sync pull

This exports the configured entities into ./uniform-backup.

Store it safely

• Commit ./uniform-backup to a private Git repo, or

• Upload it to encrypted object storage (S3/Azure/GCS) with lifecycle/retention rules

Recommended schedule

• Nightly (minimum) for production

• Also run a snapshot before major launches or large migrations

Step 4 — Restore (Import) with Caution

To restore from backup files:

uniform sync push

Important warning about restore modes

• In mirror mode, a push can delete content in the target Uniform project if it doesn’t exist in your backup files.

• For many recovery scenarios, a safer approach is restoring into a non-production project first, validating, then proceeding.

Safer restore workflow (recommended):

1. Restore into a staging/test Uniform project

2. Validate content integrity and routing/project map behavior

3. Communicate downtime/change window if production must be overwritten

4. Restore production only after verification

Always re-check entity coverage: if your backup didn’t export an entity type, you can’t restore it via CLI.

Best Practices (Applies to Both Methods)

• Use both webhooks + snapshots for redundancy.

• Secure backups: treat exported content as sensitive data; restrict access and encrypt at rest.

• Test restores regularly: a backup that hasn’t been restored is unproven.

• Monitor and alert:

  • webhook delivery failures

  • receiver errors / queue backlog

  • scheduled CLI job failures

• Retention policy:

  • Git history often covers long-term retention

  • For object storage, implement time-based retention (e.g., daily 30 days, weekly 6 months)

Related References

• Uniform webhook event types: (link to the canonical “event types” documentation in your docs set)

• Uniform webhook signature verification: (link to signature verification docs)

• Uniform CLI sync docs: (link to CLI sync/pull/push docs)

Summary

• Use webhooks to capture changes continuously (with signature verification, dedupe, and reliable storage).

• Use the Uniform CLI to create periodic full snapshots and enable disaster recovery restores.

• Store backups outside Uniform (Git/object storage), and test restores to ensure recoverability.