The event and delivery log is Outpost's record of what happened to each event: the event as it was received, and every delivery attempt made for it. It's what backs the events API, the tenant user portal, and manual retries.

This is separate from application logging, which covers the stdout and audit logs your services produce.

What's stored

Outpost records two kinds of thing:

• Events — the payload and metadata as published, along with the tenant, topic, and time.
• Delivery attempts — one record per attempt against a destination, with the outcome, the destination's response, and the attempt number.

Configuration data lives elsewhere. Tenants and destinations are stored in Redis, so removing log data never affects a tenant's configured destinations.

When an event is written

An event is written to the log together with its first delivery attempt, rather than at the moment it's published.

Outpost matches each published event against the tenant's destinations. An event with no matches produces no delivery attempt and isn't written to the log.

Choosing a backend

Outpost stores logs in one of the following. Set the corresponding variable to select it, and see the Configuration Reference for the full set of connection variables.

• PostgreSQL — POSTGRES_URL
• ClickHouse — CLICKHOUSE_ADDR

PostgreSQL is the simpler choice if you already run it and don't expect to accumulate a large log. Note that it has no built-in retention, so you manage that yourself.

ClickHouse holds its query performance as the log grows. That matters most for the Metrics API, which aggregates across the same event and delivery data to produce charts, and where those aggregations get expensive on PostgreSQL once the log is large. It's what Hookdeck operates.

How much log you accumulate depends on your event volume, payload sizes, and retry behavior, so benchmark against your own data. As a rough guide, PostgreSQL tends to be comfortable into the low millions of rows per table, or per partition if you partition the tables yourself.

Switching backends later means migrating your existing log data, so it's worth deciding before you accumulate history.

Retention

Retention determines how long event history stays queryable through the API and the tenant user portal, and how long an event remains available for manual retry. It's a product decision as much as a storage one: a seven day retention means your tenants can't retry anything older than a week.

ClickHouse

Set CLICKHOUSE_LOG_RETENTION_TTL_DAYS to the number of days to keep. 0, the default, retains logs indefinitely.

Variable	Default	Description
CLICKHOUSE_LOG_RETENTION_TTL_DAYS	0	Days to retain event and delivery logs. 0 retains indefinitely.

Outpost applies the value as a ClickHouse TTL on startup, so a change takes effect on the next restart and applies to existing data as well as new logs.

PostgreSQL

Outpost has no built-in retention for PostgreSQL. Without an external retention process, the log grows indefinitely.

The straightforward approach is a scheduled batched delete, oldest first, removing attempts before events:

DELETE FROM attempts WHERE time < now() - interval '30 days';
DELETE FROM events   WHERE time < now() - interval '30 days';

Run these in bounded batches rather than as a single statement, on whatever scheduler you already operate, such as a Kubernetes CronJob, a systemd timer, or pg_cron if the extension is available to you. Both tables have a primary key leading with time, so these are index range scans rather than full table scans. You'll still take the dead tuple and vacuum cost that any large delete incurs.

The events and attempts tables are declared as range partitioned on time, but Outpost creates only DEFAULT partitions and doesn't manage the partition lifecycle. Dropping expired partitions is cheaper than deleting rows at scale, so if you're running PostgreSQL at volume, managing partitions yourself with a tool like pg_partman is worth considering.

Querying

Event and delivery history is available through the events endpoints of the Outpost API, and to your tenants through the tenant user portal. The Metrics API aggregates over the same data.

All three are backed by whichever log store you configured, so query performance and retention follow from that choice.