How to Decide Which Data to Include in an Integration Event

Designing an integration event may seem like a technical decision, but it determines team autonomy, operational resilience, and the quality of the information received by each process. When a CRM, an ERP, an ecommerce platform, and a customer service platform exchange events, one recurring question arises: should the message include all the data needed, or only a reference to retrieve it from the source system?

There is no universal answer. An event that is too sparse forces chained lookups and turns the source system into a constant dependency. One that is excessively rich duplicates information, may spread unnecessary personal data, and risks containing an already outdated version. The effective approach is to decide field by field, based on the consumer's actual use and operating conditions.

The three options for carrying context

An event can provide context in three ways. Each model solves different problems and also introduces costs that must be explicitly accepted.

Event with complete data

The message includes the information the consumer needs to perform its action. For example, an order-confirmed event may carry order lines, delivery address, sales channel, and a snapshot of the confirmed amounts.

• Use it when the consumer must act immediately, when the value sent must be retained as historical evidence, or when the source system will not have guaranteed availability.
• It reduces subsequent calls, latency, and runtime coupling.
• It requires defining what the information represents: usually a snapshot at the time of the event, not the record's current live state.
• It increases message size, contract complexity, and the data exposure surface.

Event with an identifier and later lookup

The message contains an identifier, the event type, and minimal metadata; the consumer then queries an API or an authorized replica. It is appropriate when the consumer needs the current value rather than a historical snapshot.

• Use it for volatile attributes, large catalogs, or information the consumer needs only in exceptional cases.
• It avoids distributing copies of data that changes frequently.
• It introduces dependencies on source-system availability, permissions, usage limits, and latency.
• It can cause cascading lookups: one service retrieves the order, then the customer, then the product, and finally inventory. That chain is often fragile and difficult to diagnose.

Hybrid model

In most mature integrations, the best outcome is hybrid: the event carries a self-sufficient core to execute the flow and references to enrich it when necessary. An order can include its identifier, date, confirmed status, amounts, items, and logistics destination, while providing only the customer identifier to retrieve current contact preferences if a communication requires them.

The rule is not “send little” or “send everything”: send what is needed to reliably complete the triggered decision, and provide references for data that must be current, is costly, or is not authorized for every recipient.

Criteria for deciding each field

The right unit of decision is not the entire event, but each attribute. A single event may contain immutable, volatile, sensitive, and derived data, all of which require opposite treatments.

• Immediacy: if the consumer must act before it can query an API, the data should travel in the event. Logistics should not wait for an additional lookup to know the validated address to use for dispatch.
• Freshness: if the decision requires the latest available value, a reference is preferable. Communication preferences or the current status of an account may change after the order.
• Historical value: if it matters to reconstruct what was known when an event occurred, include a dated snapshot. The accepted price and applied taxes should not be reinterpreted using the current catalog.
• Volume and frequency: images, long descriptions, documents, or large structures rarely belong in the main message. Send a stable reference, a version, and, where appropriate, a summary.
• Availability: if an outage of the source system would block a critical process, the event should provide the minimum needed to degrade safely.
• Permissions: not every consumer that knows an identifier should receive personal, financial, or internal data. The event must not bypass the authorization model of the systems.
• Traceability: every decisive value should state which version or point in time it comes from. A field without temporal context can lead to incorrect decisions.

Also classify the data. Immutable data, such as an order identifier or creation date, is a clear candidate to travel in the event. Volatile data, such as inventory availability, usually requires a lookup or a specific update event. Sensitive data must be minimized, limited by audience, and protected according to applicable policies. Derived data, such as a segmentation or score, needs to indicate its rule, version, or validity period so that it is not mistaken for a permanent fact.

Practical matrix and design patterns

Before adding a field to the contract, the business, product, and technology teams can assess it using these questions. If several answers are affirmative in the first part, it should probably be included; if answers in the second part predominate, it should be referenced.

1. Can the consumer not complete its action without this value?
2. Must the exact version valid when the event occurred be retained?
3. Could a later lookup fail or arrive too late?
4. Is it small and stable within the process lifecycle?
5. Does it change frequently or is it needed only in particular cases?
6. Does it contain sensitive data that the consumer does not explicitly need?
7. Is there an authorized and available source to retrieve it later?
8. Can the consumer tolerate a deferred response, a cache, or manual review?

Three useful patterns follow from this assessment:

• Traceable snapshot: carry the data and add occurred_at, an event identifier, the schema version, and, where applicable, the resource version. It is ideal for amounts, accepted terms, and the operational destination.
• Enrichable reference: send a stable identifier, resource type, and, if one exists, a version. The consumer looks it up only when needed and records which response it used.
• Minimal data with controlled caching: include a minimal selection and allow enrichment from a read replica with a defined expiration period. It is useful for catalogs or non-sensitive profiles where a slight delay is acceptable.

A simple contract can clearly express the difference between an event and lookup information:

{
  "event_id": "evt_123",
  "event_type": "order.confirmed",
  "occurred_at": "2025-03-08T10:30:00Z",
  "order": {
    "id": "ord_456",
    "total_confirmed": 125.00,
    "delivery_address_snapshot": { "country": "ES" }
  },
  "customer_ref": { "id": "cus_789" }
}

The included address is an operational snapshot; the customer identifier makes it possible to retrieve current attributes with authorization. It should not be interpreted to mean that every customer field was valid or approved at the time of the order.

Availability, failures, and operational degradation

Choosing a later lookup requires designing what will happen if that lookup fails. Implementing an automatic retry is not enough: a persistent outage can create duplicates, overload the source API, and block entire queues.

Define degradation behavior before publishing the event. For each consumer, agree whether it can process with minimal data, retry later, move to an exception queue, or require manual intervention. Customer service may open a case with partial information; logistics may need to hold the shipment if a verifiable address is missing.

• Use event identifiers and idempotency so that a retry does not perform the same action twice.
• Separate temporary errors from permanent ones, such as a nonexistent reference or insufficient permissions.
• Avoid synchronized, unlimited retries that amplify a source-system incident.
• Monitor queue delay, enrichment errors, the age of the latest retrieved data, and the percentage of degraded processing.
• Keep a review path for blocked decisions, with the reason and the original event available for audit.

Versioning, security, and contract governance

Event contracts evolve. Adding an optional field is usually less risky than changing the meaning of an existing one, making an optional field mandatory, or removing information that a consumer assumed was available. Compatibility is not only about whether the message can be read; it also requires preserving its business meaning.

Assign an owner to every field and document its source, classification, semantics, format, validity, and authorized consumers. Include a schema version and treat significant semantic changes as new versions or new event types. Do not reuse a name to mean something else: a field named status without a value catalog and a temporal definition is a common source of incompatible interpretations.

For security, apply data minimization. An event distributed through shared infrastructure may reach more consumers than originally expected. Do not include personal data “just in case,” secrets, credentials, or attributes without a specific purpose. If a process needs sensitive information, consider a restricted channel or an authorized lookup rather than propagating it in a general event.

Example: order for logistics, service, and communications

Imagine that a confirmed order triggers three flows. Logistics needs items, quantities, the validated shipping address, delivery method, and confirmation date. This data should travel as a snapshot because it enables shipment preparation even if the ecommerce platform becomes unavailable.

Customer service needs the order identifier, its status, and the customer reference. It can retrieve the customer's updated history when handling an issue, provided it has permission. Transactional communications require the event type and an authorized reference to the recipient, but they do not need to receive the entire order or the customer's full profile.

This separation reduces exposure and prevents a single event from becoming an accidental replica of the CRM or ERP. It also clarifies responsibilities: the ecommerce platform emits the confirmed event, logistics uses the fulfillment snapshot, and each channel retrieves only the current context that applies to it.

Decision checklist before publishing

• Does the event describe a fact that occurred, or is it trying to replicate the full state of another system?
• Does every field have an identified consumer, purpose, and owner?
• Is it clear which fields are snapshots and which must be retrieved as current state?
• Has sensitive data been minimized and have access permissions been defined?
• Does the process continue, defer, or escalate manually if enrichment fails?
• Are there an event identifier, occurrence date, idempotency, and schema version?
• Can consumers ignore new fields without breaking?
• Are there metrics and alerts to detect failed lookups, delays, and unprocessed messages?

The right decision turns the event into a reliable business contract, not an arbitrary data container. Send enough context for the event to create value autonomously; retrieve what must be current, is sensitive, or is not essential. This reduces coupling without sacrificing traceability or operational continuity.