Architecture

Implement the Transactional Outbox Pattern

Publish integration events reliably by committing business data and outgoing messages in one database transaction.

A common failure occurs when an application commits a database change and then fails before publishing the corresponding message. The database says the order exists, but downstream systems never hear about it.

Write state and message together

The transactional outbox stores an outgoing event in the same database transaction as the business change. If the transaction rolls back, neither the state change nor the event remains. If it commits, a dispatcher can eventually publish the event.

Build a reliable dispatcher

A background worker reads unpublished outbox records, claims them safely, publishes them, and marks them delivered. Use leases or row-level locking to prevent multiple workers from processing the same record concurrently.

Expect duplicate delivery

A worker can publish successfully and crash before marking the row delivered. It may publish again after restart. Consumers must therefore deduplicate by event ID or make the operation idempotent.

Operate the outbox

Track pending count, oldest message age, retry count, and poison messages. Define retention and cleanup only after delivery is confirmed and required audit retention is satisfied.

Checklist

  • Insert outbox rows in the business transaction.
  • Claim work safely across workers.
  • Expect at-least-once delivery.
  • Make consumers idempotent.
  • Monitor backlog and repeated failures.
Share this page Help other developers discover this resource.