Topics

Topics (also known as event types) allow you to categorize events and route them to matching destinations. Each destination subscribes to one or more topics, and only receives events published under those topics.

Topics determine:

  • Which topics destinations can subscribe to
  • Valid values for the topic field in the Publish Event API
  • Topics displayed in the tenant portal

Topics are optional and if none are set then the topic field should be undefined when publishing events and creating destinations.

Configuring Available Topics

Available topics are configured through the Hookdeck dashboard project settings or Config API. Topics determine which values are valid for the topic field when publishing events and which topics appear in the tenant portal.

Wildcard topic subscriptions are disabled by default. Enable them in project settings or through the Config API with TOPICS_ALLOW_WILDCARDS=true.

Set the list of available topics using the TOPICS environment variable:

TOPICS=user.created,user.updated,user.deleted,order.placed,order.shipped

If TOPICS is not set, Outpost defaults to *, allowing any topic value.

Wildcard topic subscriptions are disabled by default. Set TOPICS_ALLOW_WILDCARDS=TRUE to allow * inside destination topic strings.

Destination Topic Subscriptions

Each destination subscribes to one or more topics. A destination receives an event only if:

  1. The destination is enabled
  2. The event's topic matches one of the destination's subscribed topics
  3. The event matches the destination's filter (if any)

Subscribe to all topics with the wildcard "*":

curl 'https://api.outpost.hookdeck.com/2025-07-01/tenants/<TENANT_ID>/destinations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
  "type": "webhook",
  "topics": ["*"],
  "config": { "url": "https://example.com/webhooks" }
}'

Subscribe to specific topics:

curl 'https://api.outpost.hookdeck.com/2025-07-01/tenants/<TENANT_ID>/destinations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
  "type": "webhook",
  "topics": ["order.placed", "order.shipped"],
  "config": { "url": "https://example.com/order-webhooks" }
}'

When wildcard topic subscriptions are enabled, destination topics can also use * inside a topic string as a wildcard that matches any run of characters. For example, user.* matches user.created and user.profile.updated, *.created matches user.created and order.created, and order.*.completed matches order.payment.completed.

When available topics are configured, wildcard patterns must match at least one available topic.

Event Fanout

A single published event is independently delivered to every destination that matches its topic. Each delivery attempt is tracked separately.

Tenant topics subscriptions

The tenant object's topics array lists all topics currently in use. This is useful for keeping track of the complete set of topics a tenant is subscribed to across all their destinations, and can help you avoid unnecessary event publishing.

curl 'https://api.outpost.hookdeck.com/2025-07-01/tenants/<TENANT_ID>' \
--header 'Authorization: Bearer <API_KEY>'

{
  "id": "org_acme",
  "topics": ["user.created", "order.placed"]
  [...]
}

You can also subscribe to the tenant.subscriptions.updated Operator Events topic to receive an event when the tenant's subscribed topics change.

<- Previous Multi-Tenancy Next -> Destination Filters