Migrate from Hookdeck Outpost

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

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

await outpost.publish({
  id: "evt_9001",
  tenantId: "customer_42",
  topic: "invoice.paid",
  data: { invoice_id: "inv_123", amount: 4900 },
});

import { WebhookRelay } from "@webhookrelay/sdk";

const relay = new WebhookRelay(); // reads RELAY_KEY and RELAY_SECRET

await relay.outbound.messages.publish(
  { consumer: "customer_42", eventType: "invoice.paid", eventId: "evt_9001", payload: { invoice_id: "inv_123", amount: 4900 } },
  { idempotencyKey: "evt_9001" },
);

// Before
_, err := s.Publish(ctx, components.PublishRequest{
    ID:       outpostgo.Pointer("evt_9001"),
    TenantID: outpostgo.Pointer("customer_42"),
    Topic:    outpostgo.Pointer("invoice.paid"),
    Data:     map[string]any{"invoice_id": "inv_123", "amount": 4900},
})

// After
_, err := api.PublishOutboundMessage(&webhookrelay.OutboundMessagePublishOptions{
    Consumer:       "customer_42",
    EventType:      "invoice.paid",
    EventID:        "evt_9001",
    Payload:        map[string]interface{}{"invoice_id": "inv_123", "amount": 4900},
    IdempotencyKey: "evt_9001",
})

# Before
curl -X POST https://api.outpost.hookdeck.com/2025-07-01/publish \
  -H "Authorization: Bearer $OUTPOST_API_KEY" -H 'Content-Type: application/json' \
  -d '{"id":"evt_9001","tenant_id":"customer_42","topic":"invoice.paid","data":{"invoice_id":"inv_123","amount":4900}}'

# After
curl --user "$RELAY_KEY:$RELAY_SECRET" -X POST https://my.webhookrelay.com/v1/outbound/messages \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: evt_9001' \
  -d '{"consumer":"customer_42","event_type":"invoice.paid","event_id":"evt_9001","payload":{"invoice_id":"inv_123","amount":4900}}'

// Before
await outpost.tenants.upsert("customer_42");
// POST /tenants/customer_42/destinations {"type":"webhook","topics":["invoice.paid"],"config":{"url":"https://acme.example/webhooks"}}

// After
await relay.outbound.consumers.upsert("customer_42", { name: "Acme" });
const endpoint = await relay.outbound.endpoints.create("customer_42", {
  url: "https://acme.example/webhooks",
  eventTypes: ["invoice.paid"],
  autoDisable: true,
});
// endpoint.secret is the customer's new whsec_ secret. Store it like a password.

# OUTPOST_SECRET holds the destination's credentials.secret. Never echo it.
jq -n --arg url "https://acme.example/webhooks" --arg secret "$OUTPOST_SECRET" \
  '{url: $url, event_types: ["invoice.paid"], secret: $secret}' |
curl -s --user "$RELAY_KEY:$RELAY_SECRET" -X POST \
  https://my.webhookrelay.com/v1/outbound/consumers/customer_42/endpoints \
  -H 'Content-Type: application/json' --data @- | jq '{id, state}'

import crypto from "node:crypto";
import { verifyWebhook } from "./verify-webhook.js"; // from the receiving guide

export function verify(rawBody, headers) {
  if (headers["webhook-signature"]) {
    // Standard Webhooks: the key is the base64-decoded part after "whsec_".
    // If the secret wasn't imported, pass the new Webhook Relay secret here instead.
    return verifyWebhook(rawBody, headers, process.env.WEBHOOK_SECRET);
  }
  const header = headers["x-outpost-signature"]; // "v0=<hex>[,<hex>]" with Outpost's default templates
  if (!header?.startsWith("v0=")) return false;
  // Outpost default mode: the key is the whole secret string.
  const expected = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(rawBody).digest();
  return header.slice(3).split(",").some((sig) => {
    const received = Buffer.from(sig, "hex");
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

// migrate-outpost.mts
// Env: OUTPOST_API_KEY, OUTPOST_API_URL (default managed; self-hosted: https://<host>/api/v1), TENANT_IDS (optional),
//      RELAY_KEY, RELAY_SECRET (token with "Outbound: manage"), DRY_RUN=false to write.
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { WebhookRelay, WebhookRelayAPIError } from "@webhookrelay/sdk";

const OUTPOST_API = process.env.OUTPOST_API_URL ?? "https://api.outpost.hookdeck.com/2025-07-01";
const DRY_RUN = process.env.DRY_RUN !== "false";
const STATE_FILE = "migration-state.json"; // source destination ID -> Webhook Relay endpoint ID. Never secrets.
const ID = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/;
const RESERVED = /^(webhook-|host$|content-length$|transfer-encoding$|connection$)/i;
const RELAY_AUTH = `Basic ${Buffer.from(`${process.env.RELAY_KEY}:${process.env.RELAY_SECRET}`).toString("base64")}`;

const relay = new WebhookRelay();

type PlanEndpoint = {
  sourceId: string; url: string; eventTypes: string[]; description?: string;
  headers?: Record<string, string>; rate?: number; disabledAtSource?: boolean;
  secret?: string; // in memory only: never printed, logged or written to the state file
};

// Webhook Relay imports 32-100 standard base64 characters (padded or not) with an optional whsec_ prefix.
// Anything else (URL-safe base64, other characters, wrong length) gets a new generated secret.
function importableSecret(secret: unknown): string | undefined {
  if (typeof secret !== "string") return undefined;
  const encoded = secret.replace(/^whsec_/, "");
  const bare = encoded.replace(/={1,2}$/, "");
  if (encoded.length > 100 || !/^[A-Za-z0-9+/]{32,100}$/.test(bare) || bare.length % 4 === 1) return undefined;
  if (bare !== encoded && encoded.length % 4 !== 0) return undefined; // bad padding
  return secret;
}
type Plan = {
  eventTypes: { name: string; description?: string; deprecated?: boolean }[];
  consumers: { id: string; name?: string; endpoints: PlanEndpoint[] }[];
  warnings: string[];
};

// ---- 1. Export from Outpost (read-only) ----
async function outpost<T>(path: string, query: Record<string, string> = {}): Promise<{ status: number; body: T }> {
  const qs = new URLSearchParams(query).toString();
  const res = await fetch(`${OUTPOST_API}${path}${qs ? `?${qs}` : ""}`, {
    headers: { Authorization: `Bearer ${process.env.OUTPOST_API_KEY}` },
  });
  if (res.status === 501) return { status: 501, body: undefined as T };
  if (!res.ok) throw new Error(`Outpost GET ${path}: ${res.status} ${await res.text()}`);
  return { status: res.status, body: (await res.json()) as T };
}

async function tenantIds(): Promise<{ id: string; name?: string }[]> {
  if (process.env.TENANT_IDS) return process.env.TENANT_IDS.split(",").map((id) => ({ id: id.trim() }));
  const out: { id: string; name?: string }[] = [];
  let next: string | undefined;
  for (;;) {
    const { status, body } = await outpost<{ models: any[]; pagination?: { next?: string | null } }>(
      "/tenants", { limit: "100", ...(next ? { next } : {}) });
    if (status === 501) throw new Error("GET /tenants is not available on this instance: set TENANT_IDS");
    for (const t of body.models) out.push({ id: t.id, name: t.metadata?.name });
    if (!body.pagination?.next) return out;
    next = body.pagination.next;
  }
}

async function exportPlan(): Promise<Plan> {
  const plan: Plan = { eventTypes: [], consumers: [], warnings: [] };
  const topics = (await outpost<string[]>("/topics")).body;
  plan.eventTypes = topics.map((name) => ({ name }));
  const expand = (t: string | string[]): string[] => {
    const list = Array.isArray(t) ? t : [t];
    if (list.includes("*")) return ["*"];
    return [...new Set(list.flatMap((p) => {
      if (!p.includes("*")) return [p];
      const re = new RegExp(`^${p.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
      return topics.filter((name) => re.test(name));
    }))];
  };
  for (const tenant of await tenantIds()) {
    const consumer = { id: tenant.id, name: tenant.name, endpoints: [] as PlanEndpoint[] };
    const { body: destinations } = await outpost<any[]>(`/tenants/${encodeURIComponent(tenant.id)}/destinations`);
    for (const d of destinations) {
      if (d.type !== "webhook") {
        plan.warnings.push(`${tenant.id}: ${d.type} destination ${d.id} skipped (only HTTPS endpoints are supported)`);
        continue;
      }
      if (d.filter) plan.warnings.push(`${tenant.id} ${d.config.url}: has a filter; recreate it as a Function`);
      const secret = importableSecret(d.credentials?.secret);
      if (!secret) plan.warnings.push(`${tenant.id} destination ${d.id}: secret doesn't fit the import format; the endpoint gets a new one`);
      const custom = d.config.custom_headers ? JSON.parse(d.config.custom_headers) : {};
      const headers = Object.fromEntries(Object.entries(custom).filter(([k]) => !RESERVED.test(k))) as Record<string, string>;
      consumer.endpoints.push({
        sourceId: d.id, url: d.config.url, eventTypes: expand(d.topics), headers,
        disabledAtSource: Boolean(d.disabled_at), secret,
      });
    }
    plan.consumers.push(consumer);
  }
  return plan;
}

// ---- 2. Check access and limits before writing anything ----
async function checkPlan(plan: Plan) {
  const res = await fetch("https://my.webhookrelay.com/v1/outbound/access", { headers: { Authorization: RELAY_AUTH } });
  const access = await res.json();
  if (!access.enabled) throw new Error("The Outbound Gateway isn't available on this account: upgrade to Basic or above.");
  const limits = access.limits as { consumers: number; endpoints_per_consumer: number; event_types: number };

  const haveConsumers = new Set((await relay.outbound.consumers.list()).map((c) => c.id));
  const haveTypes = new Set((await relay.outbound.eventTypes.list()).map((e) => e.name));
  const consumers = new Set([...haveConsumers, ...plan.consumers.map((c) => c.id)]).size;
  const types = new Set([...haveTypes, ...plan.eventTypes.map((e) => e.name)]).size;

  const problems: string[] = [];
  if (consumers > limits.consumers) problems.push(`${consumers} consumers exceed the limit of ${limits.consumers}`);
  if (types > limits.event_types) problems.push(`${types} event types exceed the limit of ${limits.event_types}`);
  for (const et of plan.eventTypes) if (!ID.test(et.name)) problems.push(`event type "${et.name}" is not a valid name`);
  for (const c of plan.consumers) {
    if (!ID.test(c.id)) problems.push(`consumer "${c.id}" is not a valid ID: map it to your own customer ID`);
    if (c.endpoints.length > limits.endpoints_per_consumer)
      problems.push(`${c.id} has ${c.endpoints.length} endpoints, the limit is ${limits.endpoints_per_consumer}`);
    for (const e of c.endpoints) {
      if (!e.url.startsWith("https://")) problems.push(`${c.id} ${e.url}: endpoints must be public HTTPS`);
      if (e.eventTypes.length === 0) problems.push(`${c.id} ${e.url}: no topics matched`);
      if (e.eventTypes.length > 100) problems.push(`${c.id} ${e.url}: more than 100 event types`);
    }
  }
  for (const w of plan.warnings) console.warn(`warning: ${w}`);
  if (problems.length) {
    console.error(`Not importing:\n- ${problems.join("\n- ")}`);
    process.exit(1);
  }
}

// ---- 3. Import into Webhook Relay ----
const state: Record<string, string> = existsSync(STATE_FILE) ? JSON.parse(readFileSync(STATE_FILE, "utf8")) : {};

class RelayError extends Error {
  constructor(readonly status: number, message: string) { super(message); }
}

// REST create, because the SDKs expose `secret` only from their next release. Webhook Relay's errors never echo the secret.
async function createEndpoint(consumer: string, e: PlanEndpoint): Promise<{ id: string }> {
  const res = await fetch(`https://my.webhookrelay.com/v1/outbound/consumers/${encodeURIComponent(consumer)}/endpoints`, {
    method: "POST",
    headers: { Authorization: RELAY_AUTH, "Content-Type": "application/json" },
    body: JSON.stringify({
      url: e.url, event_types: e.eventTypes, description: e.description, headers: e.headers, rate: e.rate,
      ...(e.secret ? { secret: e.secret } : {}),
    }),
  });
  if (!res.ok) throw new RelayError(res.status, `create endpoint: ${res.status} ${await res.text()}`);
  const { id } = (await res.json()) as { id: string }; // the response also has the secret: don't log or store it
  return { id };
}

async function step<T>(what: string, fn: () => Promise<T>): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = err instanceof WebhookRelayAPIError || err instanceof RelayError ? err.status : 0;
      if (status === 429 && attempt < 5) {
        await new Promise((r) => setTimeout(r, attempt * 2000));
        continue;
      }
      console.error(`Stopped at ${what}: ${err instanceof Error ? err.message : String(err)}`);
      console.error(`Progress is saved in ${STATE_FILE}. Fix the cause and run the script again.`);
      process.exit(1);
    }
  }
}

async function importPlan(plan: Plan) {
  for (const et of plan.eventTypes) {
    await step(`event type ${et.name}`, () =>
      relay.outbound.eventTypes.upsert(et.name, { description: et.description, deprecated: et.deprecated }));
  }
  for (const c of plan.consumers) {
    await step(`consumer ${c.id}`, () => relay.outbound.consumers.upsert(c.id, { name: c.name }));
    for (const e of c.endpoints) {
      if (state[e.sourceId]) continue; // imported on an earlier run
      const { id, created } = await step(`endpoint ${c.id} ${e.url}`, async () => {
        try {
          return { ...(await createEndpoint(c.id, e)), created: true };
        } catch (err) {
          if (err instanceof RelayError && err.status === 409) {
            const existing = (await relay.outbound.endpoints.list(c.id)).find((x) => x.url === e.url);
            if (existing) return { id: existing.id, created: false }; // already there: leave its state alone
          }
          throw err;
        }
      });
      if (created) await step(`pause ${id}`, () => relay.outbound.endpoints.pause(id));
      state[e.sourceId] = id;
      writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
      const secretNote = created ? (e.secret ? ", secret imported" : ", NEW secret") : "";
      console.log(`${c.id}: ${e.url} -> ${id} ${created ? "(created, paused" : "(already existed, unchanged"}${secretNote})${e.disabledAtSource ? " [disabled at Outpost]" : ""}`);
    }
  }
}

const plan = await exportPlan();
await checkPlan(plan);
const endpoints = plan.consumers.flatMap((c) => c.endpoints);
const imported = endpoints.filter((e) => e.secret).length;
console.log(`Plan: ${plan.eventTypes.length} event types, ${plan.consumers.length} consumers, ${endpoints.length} endpoints (${imported} with an imported secret, ${endpoints.length - imported} with a new one).`);
if (DRY_RUN) console.log("Dry run: nothing was written. Run again with DRY_RUN=false to import.");
else await importPlan(plan);