Integration code has a habit of inheriting every unresolved decision in a program. It becomes the place where naming inconsistencies, process gaps, and timeline pressure all arrive disguised as payload transformation.

The boundary is part of the product

An integration boundary is not just plumbing. It is a contract surface with real user consequences. If the contract is vague, the implementation will compensate with tribal knowledge and hidden conditionals.

  1. Define who owns each field and state transition.
  2. Separate transport success from business success.
  3. Store enough context to replay failures safely.
  4. Document what happens when the downstream system disagrees.

Observability should travel with the message

Correlation identifiers, lifecycle timestamps, and source-of-truth markers should move through the system with the payload. Retrofitting visibility after incidents is usually more expensive than carrying context from the start.

A minimal envelope that preserves debugging contextjson
{
  "correlationId": "evt_01J2...",
  "sourceSystem": "commerce-cloud",
  "eventType": "order.submitted",
  "occurredAt": "2026-05-18T14:02:11.102Z",
  "payloadVersion": "2026-05"
}