Event-Driven SaaS with the Outbox Pattern: Reliable Events Without Dual Writes

If your SaaS app writes to a database and then publishes a message to a queue in the same request, you are one partial failure away from data inconsistency.

This is the classic dual-write problem:

1. You save invoice.status = paid in your database.
2. Then you publish invoice.paid to your broker.
3. The broker call fails (timeout, network blip, deploy restart).

Now your source of truth says “paid,” but downstream systems never get notified. Finance, analytics, and notification pipelines drift out of sync.

The outbox pattern is the most practical fix. It gives you reliable event publishing without distributed transactions.

Why Distributed Transactions Usually Aren’t the Answer

In theory, two-phase commit can make DB + broker updates atomic. In practice, it adds coupling, latency, and operational complexity across systems that may not even support the same transaction model.

Most production SaaS teams need something simpler:

• Strong consistency in the primary datastore
• Eventually consistent delivery to other systems
• Safe retries and observability

That is exactly what the outbox pattern provides.

The Core Idea

Instead of publishing directly to Kafka/SQS/NATS in your request handler, you write an event record to an outbox table in the same database transaction as your domain change.

Later, a background worker reads pending outbox rows and publishes them.

If the publish fails, the row stays pending and is retried.

Data Flow

1. API request updates business data.
2. Same DB transaction inserts outbox record.
3. Worker polls/claims outbox rows.
4. Worker publishes message.
5. Worker marks row as sent (or schedules retry).

No dual write. Either both domain change + outbox entry commit, or neither do.

Minimal Schema

create table outbox_events (
  id uuid primary key,
  aggregate_type text not null,
  aggregate_id text not null,
  event_type text not null,
  payload jsonb not null,
  occurred_at timestamptz not null default now(),

  status text not null default 'pending', -- pending | sent | failed
  attempts int not null default 0,
  next_attempt_at timestamptz not null default now(),
  sent_at timestamptz,
  last_error text
);

create index outbox_pending_idx
  on outbox_events (status, next_attempt_at)
  where status = 'pending';

Application Write Path (TypeScript)

import { randomUUID } from "node:crypto";

async function markInvoicePaid(db: DbClient, invoiceId: string, paidAt: string) {
  await db.transaction(async (tx) => {
    await tx.query(
      `update invoices set status = 'paid', paid_at = $1 where id = $2`,
      [paidAt, invoiceId]
    );

    await tx.query(
      `insert into outbox_events
       (id, aggregate_type, aggregate_id, event_type, payload)
       values ($1, $2, $3, $4, $5::jsonb)`,
      [
        randomUUID(),
        "invoice",
        invoiceId,
        "invoice.paid",
        JSON.stringify({ invoiceId, paidAt }),
      ]
    );
  });
}

The transaction boundary is the guarantee. If this transaction commits, your event is durably queued for publishing.

Publisher Worker

A worker continuously claims due rows and publishes them.

const BATCH_SIZE = 100;

async function claimPendingEvents(db: DbClient) {
  return db.query(
    `with cte as (
       select id
       from outbox_events
       where status = 'pending'
         and next_attempt_at <= now()
       order by occurred_at
       limit $1
       for update skip locked
     )
     update outbox_events o
     set attempts = attempts + 1
     from cte
     where o.id = cte.id
     returning o.*`,
    [BATCH_SIZE]
  );
}

function backoffSeconds(attempt: number) {
  return Math.min(300, Math.pow(2, attempt));
}

async function processEvent(db: DbClient, broker: Broker, e: OutboxEvent) {
  try {
    await broker.publish(e.event_type, e.payload, {
      messageId: e.id, // useful for downstream idempotency
      occurredAt: e.occurred_at,
    });

    await db.query(
      `update outbox_events
       set status = 'sent', sent_at = now(), last_error = null
       where id = $1`,
      [e.id]
    );
  } catch (err) {
    await db.query(
      `update outbox_events
       set next_attempt_at = now() + ($2 || ' seconds')::interval,
           last_error = $3,
           status = case when attempts >= 12 then 'failed' else 'pending' end
       where id = $1`,
      [e.id, backoffSeconds(e.attempts), String(err)]
    );
  }
}

Important details:

• FOR UPDATE SKIP LOCKED enables safe parallel workers.
• Exponential backoff prevents hot-loop retries.
• Capped attempts move poison messages to failed for manual handling.

Consumer Idempotency Is Still Required

The outbox pattern gives reliable at-least-once delivery, not exactly-once. Your consumers must deduplicate.

A simple approach:

• Include stable event ID in every message
• Store processed IDs in consumer DB
• Ignore duplicates when ID already exists

This protects you from retries and broker redeliveries.

Operational Guardrails

The pattern is easy to implement but easy to under-operate. Add these from day one:

• Lag metric: oldest pending event age (now - min(occurred_at)).
• Throughput metric: events sent per minute.
• Failure rate: failed publishes / total publishes.
• Dead-letter visibility: dashboard for status = failed.
• Alerting: page when lag exceeds your SLO.

Without these, teams discover broken pipelines from customer tickets instead of monitoring.

Polling vs CDC

You can publish outbox rows in two common ways:

1. Polling worker (shown above)

   • Easiest to build
   • Works everywhere
   • Slightly higher latency

2. CDC (change data capture) with tools like Debezium

   • Lower latency and less custom worker code
   • More infra complexity
   • Best when event volume is high

For most teams, start with polling and upgrade to CDC only when needed.

Common Mistakes

1. Publishing in request path anyway
   • Undermines the whole pattern.
2. No retry scheduling
   • Creates permanent data loss during transient outages.
3. No dead-letter handling
   • Poison messages disappear silently.
4. No consumer idempotency
   • Duplicates cause side effects.
5. Never deleting sent rows
   • Outbox table grows forever.

Add periodic retention jobs (for example, delete sent rows older than 30 days or archive them).

When the Outbox Pattern Is a Great Fit

Use it when:

• Your app is database-centric
• You need reliable event propagation to multiple systems
• You can tolerate eventual consistency
• You want simple, auditable failure recovery

If this describes your SaaS platform, the outbox pattern is usually the highest-leverage reliability upgrade you can ship in a sprint.

Reliable eventing is less about exotic infrastructure and more about disciplined transaction boundaries. The outbox pattern turns “best effort” messaging into a system you can trust.