# Hookdeck Outpost Quickstart: TypeScript

[Hookdeck Outpost](https://outpost.hookdeck.com) is Hookdeck’s managed [Outpost](https://github.com/hookdeck/outpost) service. Each **tenant** represents one of your platform’s customers; **destinations** are where events are delivered; **topics** route events to the right destinations.

This quickstart uses the official TypeScript SDK. Configure **topics** in the Hookdeck dashboard before publishing—use a topic name that exists there in the code below.

## Prerequisites

* A Hookdeck account with an Outpost project
* An **API key** (Outpost API key) from your project: **Settings → Secrets**
* **Topics** already configured in the dashboard
* [Node.js](https://nodejs.org/) 18+ recommended
* API base URL: `https://api.outpost.hookdeck.com/2025-07-01`

## Install the SDK

```sh
npm install @hookdeck/outpost-sdk

```

## Set up credentials

In the Hookdeck Dashboard, open your Outpost project, go to **Settings → Secrets**, and create or copy an API key. Export it (and optionally the base URL) in your shell:

```sh
export OUTPOST_API_KEY="your_api_key"
export OUTPOST_API_BASE_URL="https://api.outpost.hookdeck.com/2025-07-01"

```

The SDK defaults to the production API base URL, so `OUTPOST_API_BASE_URL` is only needed if you want to be explicit or point at another environment.

## Set environment variables

Before you run the quickstart script, define these in the same terminal session (or load them from a `.env` file if your tooling supports it).

1. **`OUTPOST_API_KEY`** — **Required.** Copy the Outpost API key from **Settings → Secrets** in your project. The script passes this to the SDK as the Bearer token. Without it, the script stops with an error.
2. **`OUTPOST_API_BASE_URL`** — **Optional.** Only set this if you need to override the API host. For Hookdeck Outpost you can omit it entirely: the SDK already uses `https://api.outpost.hookdeck.com/2025-07-01`.
3. **`OUTPOST_TEST_WEBHOOK_URL`** — **Required for this walkthrough.** The script creates a webhook destination, which must point at an HTTPS URL. Easiest path: open [Hookdeck Console](https://console.hookdeck.com?ref=outpost-docs), create a **Source**, copy its URL, and assign it to this variable so you can see the webhook payload without deploying your own server.

## Create and run the quickstart script

Save the following as `outpost-quickstart.ts`.

The script (**1)** builds an authenticated SDK client, (**2)** ensures a tenant exists, (**3)** adds a webhook destination subscribed to your topic, (**4)** publishes one test event, and (**5)** prints the event id.

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

//
// --- 1. Authenticated client (API key from Settings → Secrets) ---
//

const apiKey = process.env.OUTPOST_API_KEY;
if (!apiKey) {
  throw new Error("Set OUTPOST_API_KEY");
}

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

//
// --- 2. Tenant id, topic name, and webhook URL (from env) ---
//
// tenantId = one of your customers in Outpost.
// topic    = must match a topic configured in the dashboard.
//

const tenantId = "customer_acme_001";
const topic = "user.created";

const webhookUrl = process.env.OUTPOST_TEST_WEBHOOK_URL;
if (!webhookUrl) {
  throw new Error(
    "Set OUTPOST_TEST_WEBHOOK_URL to an HTTPS endpoint (e.g. a Hookdeck Console Source URL)",
  );
}

//
// --- 3. Create or update the tenant ---
//

await outpost.tenants.upsert(tenantId);

//
// --- 4. Webhook destination: Outpost delivers events on `topic` to this URL ---
//

await outpost.destinations.create(tenantId, {
  type: "webhook",
  topics: [topic],
  config: { url: webhookUrl },
});

//
// --- 5. Publish one event (delivered to destinations subscribed to `topic`) ---
//

const published = await outpost.publish({
  tenantId,
  topic,
  eligibleForRetry: true,
  metadata: { source: "quickstart" },
  data: { user_id: "user_123" },
});

console.log("Published event id:", published.id);

```

> **Publish is asynchronous (HTTP 202).** A successful `publish` means Outpost **accepted** the event and returned an **event id**. It does not mean the event is already visible in the **events** or **attempts** APIs, or that your webhook has been delivered — processing and delivery continue in the background. When the script finishes, note the printed event id and confirm delivery using the steps below. See [Publish acceptance vs observability](/docs/outpost/concepts#publish-acceptance-vs-observability) for how this differs from listing events or attempts in your own code.

Run:

```sh
npx tsx outpost-quickstart.ts

```

To subscribe the destination to all topics, pass `topics: ["*"]` instead of `[topic]`.

## Verify delivery

When the script completes, you should see a published event id in the terminal.

* In **Hookdeck Console**, open the Source or connection you used for `OUTPOST_TEST_WEBHOOK_URL` and confirm the webhook request arrived with the expected payload.
* In the **Hookdeck Dashboard**, open **your Outpost project** and review **logs** to confirm the event was processed and delivered.

Listing events with `outpost.events.list` (or `GET …/events` with `tenant_id`) immediately after publish may return an empty list for a short time while Outpost indexes the event. That is normal eventual consistency, not a failed publish — you do not need the events API to finish this walkthrough. If you are building an activity or audit screen in your product, poll with retries instead of a single list call; see [Publish acceptance vs observability](/docs/outpost/concepts#publish-acceptance-vs-observability).

### Optional: poll the events API

This continues the script above — `published` is the value returned from `outpost.publish(...)`. Use the pattern when your application needs to confirm an event appears in the events API (for example while building an activity feed):

```typescript
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
let found;
for (let attempt = 1; attempt <= 8 && !found; attempt++) {
  const { models: events } = await outpost.events.list({ tenantId, topic });
  found = events?.find((e) => e.id === published.id);
  if (!found) await sleep(1000);
}
if (!found) {
  console.warn(
    "Event not visible in the events list yet; check Hookdeck Console for delivery.",
  );
} else {
  console.log("Verified in events list:", found.id);
}

```

For this quickstart, Console and dashboard logs are sufficient.

## Next steps

* [Destination types](/docs/outpost/overview#supported-destinations)
* [Tenant user portal](/docs/outpost/features/tenant-user-portal)
* [SDKs](/docs/outpost/sdks)
* [API reference](/docs/outpost/api)