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"

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"
    }
  }'

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"
    }
  }'

A 202 response means the event was accepted for delivery.

Shell scripts: status codes and portability

If you combine API response bodies with curl --write-out '\n%{http_code}':

  • Publish success is HTTP 202 (not only 200/201). Treat 202 as success in conditional checks.
  • Portability: GNU head -n -1 (“all lines but the last”) is not available on macOS BSD head. Prefer splitting with sed '$d' (body) and tail -n 1 (status), or another POSIX-friendly approach, so the same script runs on Linux and macOS.

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

<- Previous Overview Next -> Hookdeck Outpost: TypeScript