liveBook · Manning

Integration event

As explained in Clean Applications with Hexagonal Architecture

A published event contract representing an occurrence in a stable form suitable for consumers across system boundaries.

A local listener cannot reliably notify a search service or analytics platform in another process. An integration event carries a fact across that boundary as a published contract: stable, versionable, and meaningful to consumers that do not know the internal domain model. section 6.5 section 6.5.1

A domain event uses the model’s language and can carry internal value types. An integration event instead exposes agreed fields such as primitive identifiers, timestamps, and an event ID. A local domain-event listener may run synchronously or after commit, but in-process delivery is not durable by itself. section 6.5.1

Publishing an article

ArticlePublished is an internal domain event. ArticlePublishedIntegrationEvent is a separate external contract with eventId, articleId, publishedAt, and createdAt. It omits author, title, and content; consumers needing more data can query the API using articleId. section 6.5.2

Listing 6.13 A contract for external consumers
public record ArticlePublishedIntegrationEvent(#A
  String eventId, #B
  String articleId, #C
  Instant publishedAt,
  Instant createdAt) {
}

The Java record shows the external contract without exposing internal domain types. section 6.5.2

The domain decides what happened; the application layer decides whether and in what shape that fact leaves the boundary. An adapter handles the external format and delivery mechanics. Choose an event when other systems can react later rather than the use case needing an immediate answer. section 10.5 section 10.4

Publishing directly to a broker alongside a database update creates a dual-write failure: either operation may succeed without the other. A transactional outbox records the integration event in the same transaction as the business change. A separate poller or change-data-capture relay forwards committed records to the broker. section 6.5.3

For atomic recording, the outbox write must happen before the originating transaction commits. An after-commit listener can start an independent follow-up use case, but it cannot make its outbox write atomic with the already committed change. A failed before-commit outbox write instead aborts the publication. section 9.0 section 9.8

The relay delivers at least once, so consumers must handle duplicates. One approach is to record processed event IDs and skip repeats; this is a consumer-side responsibility. section 6.5.3

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Develops contract design and transactional outbox recording, while leaving the relay implementation outside the complete application example.
Examples
Uses an article-publication event with an event ID, article ID, publication time, and creation time.
What you can do after
Builds an integration-event contract and records publication intent atomically through an outbox adapter.
How it connects
Connects domain events, bounded contexts, transactional outbox, adapters, and idempotency.

Also explained in

Compare how 2 books explain integration event →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.