Salesforce CDC: Read the ChangeEventHeader Before the Payload

A Salesforce Change Data Capture event contains business fields, but a robust consumer also needs the change metadata in ChangeEventHeader.

Conceptually, the consumer needs to understand questions such as:

What type of change occurred?
Which record was involved?
Which fields changed?
What transaction context is associated with the event?

Do Not Treat CDC as a Full Record Snapshot

CDC represents changes. A consumer should not casually assume every field required to reconstruct the complete Salesforce record is present in every event.

That leads to an important design decision:

CDC event -> apply change information directly

or

CDC event -> identify record -> fetch authoritative current state

The right choice depends on the consumer's consistency, latency and API-usage requirements.

Change Type Influences Processing

Create, update, delete and undelete changes do not necessarily belong in the same downstream logic.

A delete event, for example, may provide enough identity to remove or deactivate a downstream representation without requiring the same field mapping used for an update.

Changed Fields Can Reduce Work

When an integration only cares about a subset of attributes, change metadata can help avoid unnecessary downstream updates.

Conceptually:

changed fields: [Name, Phone]
consumer cares about: [BillingCountry]
=> no relevant business change

Whether this optimization is worthwhile depends on processing cost and business semantics.

Keep Replay Separate from Business Identity

The event stream's replay position is not the Salesforce record's business identity. Store and use each for its intended purpose.

Final Principle

For CDC consumers, the payload tells you business data, while ChangeEventHeader tells you how to interpret the change. Design processing around both.