Migrate Existing Webhooks to Outpost

In managed Outpost, prefer the Config API for migration automation and anything you want to drive from scripts, pipelines, or infrastructure-as-code. The same values are editable in the Hookdeck dashboard under your Outpost project when you want to review or change settings by hand.

Topics and retry defaults

Use the Config API with TOPICS, MAX_RETRY_LIMIT, RETRY_INTERVAL_SECONDS, and RETRY_SCHEDULE so topic and retry defaults stay alongside the rest of your automated migration. The same fields are available in Hookdeck General settings.

For more on how topics and delivery fit together, see Concepts and Event Delivery & Retries.

Webhook headers and signatures

Use the Config API with the DESTINATIONS_WEBHOOK_* keys to automate webhook headers, signatures, and related destination behavior (the managed counterpart to self-hosted webhook environment variables). The same options can be changed in Hookdeck Destinations settings.

See Webhook destination for templates, defaults, and the full key list.

Portal and tenant-facing options

Use the Config API with PORTAL_* keys for the refresh URL, branding, and other tenant-facing portal options. The same settings are available in Hookdeck User Portal settings.

See Tenant Portal for how those options affect operators and end users.

Tenants, destinations, and backfill

Use the Outpost API or an SDK to create or upsert tenants, create destinations (including topics and secrets), and publish or backfill historical events in batches—this is the path that scales for migration automation. Config keys and dashboard settings above define platform defaults; this step is about moving organizations and subscriptions into Outpost.

You can also perform many tenant and destination actions from the Hookdeck dashboard when you want a manual or exploratory workflow alongside scripted migration.

For walkthroughs, see the curl, TypeScript, Python, and Go quickstarts, the API reference, and the SDKs overview.

Managed Outpost does not provide direct database access. For historical event migration, backfill by publishing historical events through the Outpost API or an SDK in controlled batches, preserving any external identifiers in metadata so downstream systems can deduplicate or correlate.

Recommended managed approach:

1. Export historical events from your existing system.
2. Re-publish them to Outpost by tenant/topic in batches.
3. Verify deliveries and retries in Hookdeck logs and metrics.
4. Gradually increase batch size and then switch live traffic.

To migrate your historical data to Outpost, you map your existing structure into Outpost’s logical model (tenants, destinations, published events). For self-hosted installs you can also inspect the PostgreSQL schema that stores the event log; the canonical definitions are the migration files under internal/migrator/migrations/postgres in the Outpost repository.

Outpost persists published events and delivery history in two time-partitioned tables:

events — one row per distinct published event (retries reuse the same row). Columns include id, tenant_id, time, topic, eligible_for_retry, matched_destination_ids (text array of destination IDs that matched the event), data (payload stored as text so JSON key order is preserved), and metadata (JSON). There is no destination_id column on events; routing to destinations is expressed through matched_destination_ids and the delivery pipeline.

attempts — one row per delivery attempt to a destination. Columns include id, event_id, tenant_id, destination_id, destination_type, topic, status, time, attempt_number, manual, code, response_data (HTTP-style response body stored as text), plus denormalized event fields (event_time, eligible_for_retry, event_data, event_metadata) for efficient querying.

Writing rows directly is possible for advanced operators, but easy to get wrong (partitions, denormalized attempt fields, and invariants enforced in application code). For historical replay, prefer publishing through the Outpost API or an SDK unless you are deliberately doing a low-level database migration.

Example Migration Script

The following uses the current @hookdeck/outpost-sdk (Outpost client, serverURL + apiKey) to mirror tenants and webhook destinations from a placeholder db module—same pattern as the runnable demo.

import process from "node:process";
import dotenv from "dotenv";
dotenv.config();

import { Outpost } from "@hookdeck/outpost-sdk";

// Replace with your own source of organizations and subscriptions.
import { default as db } from "./db";

if (!process.env.OUTPOST_API_BASE_URL || !process.env.OUTPOST_API_KEY) {
  console.error("OUTPOST_API_BASE_URL and OUTPOST_API_KEY are required");
  process.exit(1);
}

const outpost = new Outpost({
  serverURL: process.env.OUTPOST_API_BASE_URL,
  apiKey: process.env.OUTPOST_API_KEY,
});

const listTopics = async () => {
  const subscriptions = db.getSubscriptions();
  const allTopics = new Set<string>();

  for (const subscription of subscriptions) {
    for (const topic of subscription.topics) {
      allTopics.add(topic);
    }
  }

  return Array.from(allTopics);
};

const migrateOrganizations = async () => {
  const migratedOrgIds: string[] = [];
  const organizations = db.getOrganizations();
  for (const organization of organizations) {
    await outpost.tenants.upsert(organization.id);
    migratedOrgIds.push(organization.id);
  }
  return migratedOrgIds;
};

const migrateSubscriptions = async (organizationId: string) => {
  const subscriptions = db.getSubscriptions(organizationId);
  for (const subscription of subscriptions) {
    await outpost.destinations.create(organizationId, {
      type: "webhook",
      config: {
        url: subscription.url,
      },
      topics: subscription.topics,
      credentials: {
        secret: subscription.secret,
      },
    });
  }
};

const main = async () => {
  const topics = await listTopics();
  console.log("Subscription topics:", topics);

  const migratedOrgIds = await migrateOrganizations();

  for (const organizationId of migratedOrgIds) {
    await migrateSubscriptions(organizationId);
  }
};

main()
  .then(() => {
    console.log("Migration complete");
    process.exit(0);
  })
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

A runnable variant lives at examples/demos/nodejs/src/migrate.ts. The examples/sdk-typescript package pins the SDK via file:../../sdks/outpost-typescript for working inside this repository; when you copy the script elsewhere, depend on @hookdeck/outpost-sdk from npm.