Domain Events vs Integration Events: When to Use Each

Domain events and integration events both represent facts that happened, but they serve different purposes and live at different system boundaries. Understanding the distinction prevents internal refactoring from breaking other teams' pipelines.

Domain events — internal signals:

• Raised by the domain model when something meaningful happens — an order item was added, a payment was validated — and consumed by handlers in the same service, often within the same transaction
• Carry rich domain objects and are published in-memory via Spring's ApplicationEventPublisher; they can change as fast as you refactor your internal domain model
• Spring Data's AbstractAggregateRoot.registerEvent() publishes them automatically after save(), keeping event raising inside the aggregate where the state transition occurs

Integration events — cross-boundary contracts:

• Cross service boundaries by being published to a message broker and consumed by other services
• Payload hygiene is critical: only primitive types, stable IDs, no references to internal domain classes; other teams don't know your domain model and should not compile against it
• A field rename in your internal domain model should never break another team's consumer — integration events prevent this by decoupling the wire format from the internal model

The translation pattern:

• A @TransactionalEventListener with phase = AFTER_COMMIT catches domain events and translates them into minimal integration events using the Outbox pattern
• Waiting for the commit ensures you only publish integration events for state changes that actually persisted to the database

I recommend treating integration events with the same versioning discipline as a public REST API — additive changes only, breaking changes require a migration strategy.