Documented Event Surface

The ceiling on event-driven design

A documented event surface is the enumerated set of state changes a platform states an external endpoint can subscribe to, together with the conditions under which they can be enabled. It is read from vendor documentation, not inferred from a product tour or a sales call.

It matters because it is a hard ceiling. A state change the vendor does not publish cannot be reacted to. It can only be polled for on a schedule, or noticed later by a person. That is a different system with different latency, different cost and a different failure mode.

Read three lists side by side

• Documented. The events the vendor publishes in its own documentation.
• Enabled. The events this specific account can actually use — plan tier, feature flag and support-request gating mean the documented surface and the available surface are two different things.
• Depended on. The state changes the proposed design assumes exist.

Entries in the third list with no counterpart in the first two are the ceiling. They decide whether the build is event-driven, poll-driven, or partly manual — and that determination belongs in the scope, not in the retrospective.

What a published event should carry

Event specifications describe the metadata that makes an event usable rather than merely present. CloudEvents defines `id`, `source`, `specversion` and `type` as required context attributes, requires producers to ensure that `source` plus `id` is unique for each distinct event, and states that consumers may treat a repeated pair as a duplicate ^{[cloudevents_spec]}. Where a platform supplies that identity, deduplication is a consumer decision. Where it does not, deduplication becomes a bespoke build on top of whatever fields happen to be present.

Delivery is separate from identity. Endpoints time out and get redeployed, so the same event may arrive more than once; whether re-processing is safe depends on whether the resulting write is repeatable ^{[rfc9110_idempotent]}. Where a write is not naturally repeatable, a provider may document an explicit key mechanism instead — Stripe is one documented example ^{[stripe_idempotency]}. Whether any other provider does the same has to be read from that provider's own documentation.

What reading the surface establishes

Where this sits

The integration and orchestration systems guide owns the surrounding architecture. A missing event is often why a write-back gap exists in the first place, and terminal state configuration determines whether the end of a sequence is even observable. This entry sits in the Glossary. Locate the capability under the Integration & Orchestration Systems domain, and use Revenue Scan for the public-signal starting point.