Hookdeck Outpost Quickstart: curl

Hookdeck Outpost is Hookdeck’s managed Outpost service: a control plane and delivery layer for event destinations (webhooks, queues, and more) scoped per tenant—each tenant is one of your platform’s customers.

This quickstart uses the REST API with curl. Topics are assumed to be configured already in the Hookdeck dashboard; use a topic name that exists there when you publish.

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 (for example user.created, order.completed)
API base URL: https://api.outpost.hookdeck.com/2025-07-01

Set up credentials

In the Hookdeck Dashboard, open your Outpost project, go to Settings → Secrets, and create or copy an API key. That value is the same Outpost API key you use for the REST API and the SDKs.

Store the API key and base URL in your shell (or in a .env file you source):

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

Use them in the requests below as $OUTPOST_API_BASE_URL and $OUTPOST_API_KEY.

Create a tenant

Each tenant maps to one of your customers. Pick a stable ID from your own system (for example a team or account ID).

TENANT_ID="customer_acme_001"

curl --request PUT "$OUTPOST_API_BASE_URL/tenants/$TENANT_ID" \
  --header "Authorization: Bearer $OUTPOST_API_KEY"

On success, the response status is 200 if this tenant ID already existed, or 201 if Outpost just created it.

Create a webhook destination

Subscribe the tenant to one or more topics you configured in the dashboard. Set config.url to an HTTPS endpoint you control.

If you do not have your own endpoint yet, open Hookdeck Console, create a Source, and paste that Source URL as the webhook URL below (or any HTTPS URL you own). Replace REPLACE_WITH_YOUR_WEBHOOK_URL accordingly.

Replace user.created with a topic that exists in your project if needed.

curl --request POST "$OUTPOST_API_BASE_URL/tenants/$TENANT_ID/destinations" \
  --header "Authorization: Bearer $OUTPOST_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "webhook",
    "topics": ["user.created"],
    "config": {
      "url": "REPLACE_WITH_YOUR_WEBHOOK_URL"
    }
  }'

On success, expect HTTP 2xx (often 201 when this destination is created for the tenant).

To receive every configured topic on this destination, set "topics": ["*"] instead.

Publish a test event

Use the same tenant ID and a topic that matches both your dashboard configuration and the destination’s topics.

curl --request POST "$OUTPOST_API_BASE_URL/publish" \
  --header "Authorization: Bearer $OUTPOST_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "tenant_id": "'"$TENANT_ID"'",
    "topic": "user.created",
    "eligible_for_retry": true,
    "metadata": {
      "source": "quickstart"
    },
    "data": {
      "user_id": "user_123"
    }
  }'

On success, the response status is 202 — the event was accepted for delivery.

HTTP status codes (quick reference)

Step	Request	Success status
Create tenant	`PUT …/tenants/{ID}`	200 or 201
Create destination	`POST …/tenants/{ID}/destinations`	2xx
Publish	`POST …/publish`	202

Verify delivery

In Hookdeck Console, inspect the connection or destination you used (for example the Source you created) and confirm the webhook request and payload look correct.
In the Hookdeck Dashboard, open your Outpost project and review logs (and any deliveries or event views your project exposes) to confirm the event was processed and delivered.

Next steps

Destination types — webhooks, AWS SQS, RabbitMQ, Hookdeck, and more
Tenant user portal — optional UI for tenants to manage their own destinations
SDKs — TypeScript, Python, Go, and others
API reference — full REST API

<- Previous Overview Next -> Hookdeck Outpost: TypeScript