> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0141 — Integration event names and the envelope

> Accepted · 2026-10-20

> [!NOTE]
>
> Amends [0078](/adr/0078-messaging-layer-eight-packages), decision 3, and
> [0117](/adr/0117-contracts-placement-and-decorator-ownership), decision C1. Closes the open
> event-naming item of 0125. Changes the name form of C27 by adding the module key (see below).

## Context

The service questionnaires used service-prefixed event names (`identity.user.created.v1`, `tenancy.tenant.<state>.v1`). The owner's
answer C27 (mem L855, 2026-10-20) fixes the form as `<aggregate>.<verb>.v<n>`, with no service prefix, and it wins over the earlier names
(contradiction C-12). On 2026-10-20 the owner confirmed the final form (mem L930): the name starts with the module key, so `billing.invoice.paid.v1`
and `identity.user.created.v1`. The module key is the one of [0131](/adr/0131-module-key-version-and-deprecation).

## Decision

1. Events are named `<module-key>.<aggregate>.<verb>.v<n>`:
   * `module-key` is the module's key from [0131](/adr/0131-module-key-version-and-deprecation), for example `billing` or `identity`;
   * `aggregate` is the entity the event is about, for example `invoice` or `user`;
   * `verb` is the event, for example `paid` or `created`;
   * `v<n>` is the version.
     Names are globally unique through the registry (C27). The module key replaces the service prefix that the questionnaires used.
2. The envelope fields are `id`, `type`, `version`, `occurredAt`, `tenant`, `actor`, `onBehalfOf`, `correlation` and `causation`,
   `traceId`, and `data`. The envelope lives in `contracts`.
3. An in-process event maps one-to-one to an integration event at the outbox.

## Consequences

* An event name says which module owns it, and the registry still enforces uniqueness.
* Consumers depend on `contracts`, not on another service's source.
* Names in the service questionnaires that carry a service prefix must be renamed to the module-key form before they are published.

## Enforcement

planned — the registry rejects a duplicate event name, and the validator rejects a name whose first segment is not a registered module key.

## Alternatives

* Service-prefixed names (I10, T2, T10): superseded by C27 (C-12).
* `<aggregate>.<verb>.v<n>` with no module key (C27 as first written): amended by the 2026-10-20 confirmation.

## Supersedes and sources

Supersedes: none. Amends: [0078](/adr/0078-messaging-layer-eight-packages) decision 3, [0117](/adr/0117-contracts-placement-and-decorator-ownership)
decision C1. Sources: owner answer C27 (`stackra-decisions-2026-10-19.md` L855, 2026-10-20; fixes STA-149); the owner's confirmed naming
(`stackra-decisions-2026-10-19.md` L930, 2026-10-20: module-key prefix); contradiction C-12.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.