Skip to main content

Publishing events

Event topics​

Every service that publishes one or more events has exactly one event topic, {service}.events, to which all of its events are published. Other services MUST NOT be able to send to it.

Subscribing​

A service subscribes to each event type it consumes with a subscription of its own: one subscription per event type per consuming service. The broker does the filtering, so a service never receives an event type it has not subscribed to, and a burst of one type never holds up another.

  • The Vault Service and the Secrets Service each consume two event types, so each has two subscriptions of its own.
  • Only the service that owns a subscription may read from it.
  • Subscription names in the diagram are illustrative.

Naming​

Event names MUST be lowercase words separated by dots, and SHOULD be in the past tense, for what happened, such as user.deleted.

Breaking changes​

A publisher MUST NOT make a breaking change to a version of an event it already publishes, except to fix a bug. A change that would break subscribers goes into a new version of the event instead, as Versioning describes.

The publisher owns an event's contract and writes the event, so a change to an existing version is breaking when the publisher stops sending something that subscribers that have not yet deployed rely on.

These changes need a new version:

  • Changing a field's type, format, meaning, or units.
  • Renaming a required field.
  • Removing a required field.
  • Making a required field optional.

These changes can be made within a version:

  • Adding a field, required or optional.
  • Making an optional field required.
  • Adding a constraint to a field.
  • Removing an optional field.