A handler that updates a database and sends a message to a broker faces a dual-write problem: either operation can succeed while the other fails. The outbox pattern records the integration event in the same database transaction as the business change, leaving delivery to a separate process. section 6.5.3
The transaction and relay have separate responsibilities:
- The handler or listener writes a pending integration event to an outbox table alongside the domain state. A commit stores both; a rollback stores neither. section 6.5.3
- A separate poller or change-data-capture process reads the outbox and forwards events to the broker. The publisher can proceed without waiting for external consumers. section 6.5.3 section 10.3.2
- Delivery is at least once, not exactly once. Consumers must handle duplicates safely, for example by recording processed event IDs and skipping repeats. section 6.5.3
Listing 6.14 Outbox table schema (simplified)
CREATE TABLE integration_event_outbox ( event_id VARCHAR(36) PRIMARY KEY, #A event_type VARCHAR(100) NOT NULL, #B payload JSONB NOT NULL, #C created_at TIMESTAMP NOT NULL, published_at TIMESTAMP #D );
A simplified outbox row stores the event ID, type, payload and creation time, plus a publication timestamp. section 6.5.3
Recording an article publication
Publishing an article raises an ArticlePublished domain event. A BEFORE_COMMIT listener dispatches a command; its handler calls an output port whose adapter records the integration event in the outbox. The article and row commit together, and an outbox failure marks the transaction for rollback. section 9.4.3 section 9.5.2
Listing 9.18 RecordIntegrationEventListener: Before commit, atomic with the article
@Slf4j
@Adapter
@RequiredArgsConstructor
public class RecordIntegrationEventListener {
private final CommandBus commandBus; #A
@TransactionalEventListener(
phase = TransactionPhase.BEFORE_COMMIT) #B
public void on(final ArticlePublished event) {
RecordIntegrationEventCommand
.validateThenCreate( #C
event.articleId(), event.authorId(), event.publishedAt())
.flatMap(this.commandBus::execute) #D
.peekLeft(error -> log.warn(
"Failed to record integration event for article [{}]: {}",
event.articleId(), error));
}
}
The listener joins the open publication transaction. Logging a returned error alone does not cause rollback; the transactional handler must mark the transaction for rollback on an outbox failure. section 9.4.3
Keep the domain event, integration event and outbox row distinct. The domain event is an in-process signal; the integration event is a stable external contract; the row is its pending storage representation. The article contract exposes an article ID and publication time, with an event ID and creation time, rather than copying all internal state. section 9.5.2 section 6.5.2
An after-commit side effect is not a substitute for the atomic outbox write: a crash or failure after commit can lose that side effect. Even with an outbox, consumers learn of changes later and may receive duplicate or out-of-order events. The illustrated implementation records intent atomically; its relay is left unimplemented. section 9.4.3 section 9.5.2 section 10.3.2



