Communication

Give every event a clear envelope

Editorial edition · 16 November 2026

The idea

An event needs more than a payload. Its identity, origin and creation time let a receiver interpret it without guessing which application produced it. Keep these shared fields separate from the business data so that transport changes do not alter their meaning.

Design choice

Choose stable field names and document whether time means occurrence or publication. An identifier should identify one event, not every event concerning the same customer. Avoid putting personal details into identifiers that will appear in logs.

Worked example

For a delivery update, carry event_id, source, occurred_at and schema_version outside the status payload. A replay retains event_id even when published_at changes.

Before you ship

  • Separate event identity from entity identity
  • Specify timestamp semantics and timezone
  • Preserve identifiers during a replay

Examples are illustrative. Adapt the checks to your own environment.

Further reading

HTTP Semantics, RFC 9110

Search the library