Features

​Topics

Outpost natively supports event topics (also known as "event types") in order to segment, filter, and route events to appropriate destinations.

​Configuring Topics

A list of available topics can be configured using the TOPICS environment variable. If TOPICS is not set, Outpost will use a default of * to allow all values. Topics determine:

• Which topics destinations can subscribe to.
• The valid input for the topic field in the Publish Event API.
• The topics available via Topic API, and the user-facing portal.

​Destinations Topic Subscriptions

A tenant can have multiple destinations that subscribe to all or specific topics. A destination can subscribe to any number of topics. A destination's topics are configured by the topics field in the Create Destination API. A destination can subscribe to all topics by setting topics to ["*"].

Events published for a given tenant are evaluated against the destination's topic subscriptions to determine if the event should be delivered. An event can match zero or many destinations.

​Creating a destination with topic subscriptions

Create destinations with the following request, replacing <TENANT_ID> and <API_KEY>. The <TYPE> must be one of the supported event destination types, and the <CONFIG> contents will depend on the event destination type.

curl --location 'localhost:3333/api/v1/<TENANT_ID>/destinations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
 "type": "<TYPE>",
 "topics": ["*"],
 "config": <CONFIG>
}'
sh

For example, the following creates a webhook destination that subscribes to all topics (*) and delivers published events to the URL https://example.test/webhooks:

curl --location 'localhost:3333/api/v1/<TENANT_ID>/destinations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
  "type": "webhook",
  "topics": ["*"],
  "config": {
    "url": "https://example.test/webhooks"
  }
}'
sh

​Evaluating Topics Before Publishing

When publishing an event, the topic field is evaluated against the destination's topic subscriptions to determine if the event should be delivered. Depending on your application, it's possible that the vast majority of published events will not match any destination topic subscriptions. While that's fine, you can reduce the number of events published and unnecessary traffic by evaluating the topic before publishing. To simplify this, the Tenant API object contains a topics array that contains all the topics used across all the tenant's destinations.

If the tenant.topics array contains the topic of the event you are about to publish, at least one destination will match. A common pattern is to store the value of the tenant.topics array in your application and use it to evaluate the topic before publishing.

---