Features

​Publishing Events

Once your first tenant is created, you can publish events to it. Events are published in one of two ways:

  1. Publishing to a configured message bus queue that Outpost will consume
  2. Making an HTTP POST request to the Publish API endpoint

Using the message queue allows for a higher publishing guarantee since there are no other dependencies other than the message queue, and you may already be publishing events requiring minimal change on your end.

Using the publishing API endpoint allows you to avoid implementing publishing to your service bus. It removes the initial publishing cost, but it adds the risk of the Outpost API being unavailable or returning an error.

The events need to follow the given structure:

{
  "id": "123", // Optional but recommended. If left empty, ID will be generated by hashing the topic, data, and timestamp.
  "tenant_id": "12345", // The tenant ID to publish the event to; must match an existing tenant, otherwise it will be ignored.
  "destination_id": "12345", // Optional. Used to force delivery to a specific destination regardless of the topic.
  "topic": "something.created", // Optional. Assumed to match ANY topic if left empty. If set, it must match one of the configured topics.
  "eligible_for_retry": true, // Optional, defaults to `true`. Controls whether an event should be automatically retried.
  "time": "2024-06-01 08:23:36.082374Z", // ISO 8601 timestamp of the event
  "metadata": {
    // Arbitrary key-value mapping for event metadata.
    "key": "value" // String, number, or boolean
  },
  "data": {
    // Freeform JSON data
    "hello": "world"
  }
}
json

Each event (without a destination_id) is evaluated against all the registered destinations. An event is delivered and logged for each eligible destination.

The metadata field in published events is merged with the destination's delivery_metadata before being translated to the destination's native format. The merge priority is: system metadata (event-id, topic, timestamp) < destination's delivery_metadata < event metadata. This means event metadata has the highest priority and can override delivery_metadata values.

For webhook destinations, the merged metadata is translated to HTTP headers. This allows you to:

  • Set static headers (like x-api-key) on the destination via delivery_metadata
  • Override or add dynamic headers on a per-event basis via the event's metadata field

If the destination does not support metadata natively, it will be included in the event payload.

​Publishing from a message bus

Refer to the respective guide for the message bus you are using to publish events:

​Event Fanout

A message published to a topic is automatically replicated and sent to multiple endpoints. This allows for parallel processing and asynchronous event notifications.

TopicsDelivery & Retries