Concepts

This page is the canonical glossary. Every other doc links here when it uses a term that has a precise meaning inside the product. Read it once; refer back when something feels ambiguous.

Tenant

A tenant is one workspace, the unit of isolation. Events, destinations, routing rules, keys, members, audit logs, and usage counters all live inside exactly one tenant. There is no cross-tenant data access at any layer. The first user in a workspace becomes the owner; additional members are invited from Settings.

In multi-product organizations, prefer one tenant per product surface rather than one tenant for the whole company, it keeps event catalogs and destination ownership clean.

Customer (sub-tenant)

A customer is one of your end-users, identified by a customerExternalId you assign. Customers exist inside a tenant. Every event carries the customerExternalId of the customer it concerns; routing rules and destinations can be customer-scoped so that "deliver order events to acme-corp's webhook" is enforceable in config rather than in your application code.

When customers manage their own destinations through the embedded portal, they only see and modify destinations bound to their own customerExternalId.

Event

An event is one immutable record of something that happened in your product: an order completed, a subscription renewed, a feature flag flipped. Events carry a canonical envelope (eventType, occurredAt, source, customerExternalId, payload, plus optional tracing fields) and are validated on ingest. Once accepted, an event is the unit of fan-out: one event can result in zero, one, or many deliveries.

Event schema

An event schema describes the shape of a payload for one eventType. Schemas are vendor-side metadata, you, the SaaS, publish the schema; your customers consume it read-only. Schemas drive payload validation on ingest, drive the field picker in the destination-config UI, and let you evolve event shapes safely with schemaVersion.

Schemas are scoped to a tenant only. They are not per-customer because the catalog of events a product emits is global to that product.

Destination

A destination is one endpoint configured to receive events: a webhook URL with credentials, an S3 bucket with a prefix, a Snowflake table with a warehouse, etc. Destinations are owned by a tenant and optionally scoped to one customer. Each destination type has its own config schema, its own auth options, and its own delivery semantics.

Routing rule

A routing rule connects events to destinations. The minimum shape is "match events where eventType = X and send to destination Y". Rules can match on event type, on payload fields, and on customer scope. A single event can match multiple rules and produce one delivery per match, fan-out is one of the things Pushrail does for you.

Transform

A transform reshapes a payload on its way to a destination. v1 transforms are declarative: rename fields, drop fields, add static fields, pull values out of nested JSON paths, wrap the payload in a destination-specific envelope. Transforms are versioned and pinned per delivery attempt so replays are deterministic.

Scripted transforms (sandboxed JS/TS) are on the roadmap for the Growth tier; see Transforms for the current capability list.

Delivery

A delivery is one (event, destination) pair. When an event matches three destinations, three deliveries are created. Each delivery moves through states (pending, in_flight, succeeded, failed, dead_lettered) and accumulates one or more attempts as Pushrail retries transient failures.

Deliveries are the unit you search, filter, and replay. The delivery log is the operational surface most teams live in.

Attempt

An attempt is one HTTP request (or warehouse insert, or S3 PUT) made to fulfill a delivery. Each attempt records request body, response status, response body, latency, and the classifier's verdict (transient triggers retry; permanent moves the delivery to failed). Attempt history is preserved for the retention window of your tier. When Private Payload Mode is enabled for the environment, the request and response bodies are shown as [sealed]; status, latency, and the error category stay visible.

Replay

A replay re-enqueues deliveries against their original destinations. Scope a replay by time window, event type, destination, or specific failure mode; choose whether to replay only failures or successes too. Replays respect idempotency, if your destination handler honors the Idempotency-Key header, a replay is safe to run. See Replay & recovery.

Environment

An environment is one of Development, Staging, or Production within a tenant. Environments share schemas and members but isolate events, destinations, keys, and deliveries. They exist so you can develop against Pushrail without polluting production data.

Audit log

The audit log records every config change: destination created, routing rule updated, key rotated, replay launched, member invited. Each entry captures actor, timestamp, IP, and a diff of what changed. Audit data is retention-tiered like delivery logs and is searchable from Settings → Audit.