Consuming Salesforce Change Data Capture Events with MuleSoft

Salesforce Change Data Capture (CDC) provides an event-driven way to react to changes in Salesforce records without repeatedly polling objects for updates.

When a CDC-enabled record changes, Salesforce publishes a change event to the event bus. MuleSoft can subscribe to those events and use them to trigger downstream integration processing.

A basic flow appears simple:

Salesforce record change
        │
        ▼
Salesforce Event Bus
        │
        ▼
MuleSoft CDC subscriber
        │
        ▼
Transformation / routing
        │
        ▼
Downstream systems

The subscription itself is only the beginning. A production design must also answer what happens during disconnections, how replay position is managed, whether duplicate delivery is safe, how failed business records are recovered, and whether downstream processing should occur directly in the subscription flow or behind another durable boundary.

This article develops that design from the MuleSoft consumer outward.

Why Use CDC Instead of Polling?

A polling integration repeatedly asks Salesforce for records that have changed since a previous checkpoint:

Scheduler
   │
   ▼
Query Salesforce
   │
   ▼
Find changed records
   │
   ▼
Process them

This can be appropriate for some workloads, particularly scheduled bulk synchronization. But it also introduces polling intervals, query load, watermark management, and delayed detection between polls.

CDC changes the interaction model:

Salesforce transaction
      │
      ▼
Change event
      │
      ▼
Subscriber reacts

This is useful when downstream systems need changes with relatively low latency or when an event-driven integration model better fits the architecture.

CDC should not automatically replace every batch or query-based integration. Large backfills, reconciliation, historical extraction, and some high-volume synchronization use cases may still require query or bulk patterns. CDC is a change-notification mechanism, not a substitute for every data movement strategy.

Enable Change Data Capture in Salesforce

CDC must first be enabled for the Salesforce entities whose changes should be published.

In Salesforce Setup, navigate to the Change Data Capture configuration and select the required entities.

For a standard object such as Account, an entity-specific CDC channel follows this form:

/data/AccountChangeEvent

Salesforce also provides a channel for changes across all selected CDC entities:

/data/ChangeEvents

An entity-specific subscription is useful when a Mule application owns processing for a particular domain. The broader channel can be useful when a consumer intentionally handles multiple enabled entities, but it also increases the need for routing and independent failure handling.

Which MuleSoft Connector Should You Use?

MuleSoft provides more than one way to consume Salesforce events.

The traditional Salesforce Connector supports channel listeners, including replay-capable listeners for CDC. MuleSoft also provides the Salesforce Pub/Sub Connector, which uses Salesforce Pub/Sub API and supports platform events and CDC through a unified event interface.

For a new event-driven integration, the Pub/Sub Connector is an important option to evaluate. MuleSoft's current documentation specifically points new Platform Event and CDC integrations toward the Salesforce Pub/Sub Connector, while the Salesforce Connector remains relevant for existing applications and other Salesforce operations.

The architectural principles in this article apply to either approach. The concrete example below uses the Pub/Sub Connector because it exposes replay configuration directly for a modern event subscription.

Basic MuleSoft Subscription

In Anypoint Studio, add the Salesforce Pub/Sub Connector and configure a Subscribe channel listener as the source of the Mule flow.

For Account CDC, configure the channel as:

/data/AccountChangeEvent

Conceptually, the Mule flow becomes:

Salesforce Pub/Sub
Subscribe Channel Listener
          │
          ▼
Normalize CDC event
          │
          ▼
Apply integration policy
          │
          ▼
Downstream processing

The Pub/Sub Connector currently supports replay choices equivalent to:

Latest — consume events published after the subscription starts
Earliest — begin with retained events available in the Salesforce event bus
Custom replay id — resume after a supplied replay position
Replay id from object store — resume using a replay ID stored in MuleSoft Object Store

The replay choice is an operational guarantee, not merely a connector setting.

Understand Salesforce Replay IDs

Each delivered event contains a Replay ID representing a position in the Salesforce event stream.

Treat the Replay ID as an opaque position, not as a business sequence number. Salesforce does not guarantee that consecutive events have contiguous Replay ID values.

Salesforce currently retains Platform Events and CDC events on the event bus for 72 hours. A subscriber can use a stored Replay ID to request events still available within that retention window.

This creates an important architectural boundary:

Replay protects short interruptions within the event-retention window. It is not a permanent system of record or an unlimited recovery mechanism.

If a consumer is unavailable beyond the retention period, another reconciliation or source-query strategy may be required.

Latest vs. Earliest vs. Stored Replay Position

The correct subscription position depends on the application lifecycle.

Latest

Use Latest when the application should process only new events from the point at which it begins listening.

This can be appropriate for a new integration after an initial synchronization has already established downstream state.

Earliest

Use Earliest when the subscriber should consume retained events currently available on the event bus.

This does not mean all historical Salesforce changes. It means the retained portion of the event stream.

Custom Replay ID

A custom position is useful for controlled recovery or testing when the desired replay point is explicitly known.

Replay ID from Object Store

For a continuously running integration, persisting replay progress can allow a restarted Mule application to continue after its previously stored position.

Conceptually:

receive event E100
      │
      ▼
process event
      │
      ▼
advance durable replay position

application restarts
      │
      ▼
read replay position
      │
      ▼
resume after E100

The timing of that checkpoint is critical.

Do Not Advance Recovery State Too Early

Imagine the consumer records the replay position before completing the required downstream work:

receive E100
   │
   ├── save replay position E100
   │
   └── call downstream system → failure

If the application restarts and resumes after E100, the failed business work can be skipped.

Now reverse the order:

receive E100
   │
   ├── downstream update succeeds
   │
   └── replay checkpoint uncertain / application crashes

E100 may be delivered again after restart.

This is a familiar distributed-systems trade-off: preventing loss generally means tolerating possible duplicate delivery.

The downstream processing therefore needs an idempotency strategy.

Replay Position Is Not Business Processing State

A replay checkpoint answers:

Where should the Salesforce subscription resume?

It does not necessarily answer:

Has every downstream business effect for all events up to this position completed successfully?

Those concepts may align in a simple consumer, but they diverge quickly when processing becomes asynchronous, parallel, or multi-stage.

For example:

CDC subscription
      │
      ▼
Mule ingestion
      │
      ▼
Internal durable queue
      │
      ├── Worker A
      ├── Worker B
      └── Worker C

The Salesforce subscriber may have successfully handed events to the internal queue even though downstream workers are still processing them.

In this architecture, the Salesforce replay position protects ingestion, while the internal platform separately protects business processing.

That separation can be extremely useful.

Consider a Durable Handoff

For lightweight integrations, the CDC listener can transform an event and call the downstream system directly.

Salesforce CDC
     │
     ▼
Mule flow
     │
     ▼
Target API

For more demanding workloads, consider inserting a durable asynchronous boundary:

Salesforce CDC
     │
     ▼
Mule ingestion
     │
     ▼
Durable messaging
     │
     ▼
Processing workers
     │
     ▼
Target systems

The durable layer might be an enterprise messaging platform selected by the organization. The point is not a specific product; it is separating the Salesforce subscription lifecycle from potentially slow or unreliable downstream processing.

Benefits can include:

absorbing downstream outages
independent worker scaling
controlled backpressure
consumer-specific retry policies
simpler Salesforce subscription recovery
fan-out to multiple processing domains

The cost is additional infrastructure and another delivery boundary that must itself be operated reliably.

Understand the CDC Event Before Mapping It

A CDC event is not simply a normal Salesforce record serialized as an event.

The change event contains metadata describing the change as well as fields associated with the changed entity. Processing logic should understand concepts such as:

the affected record identity
change type
changed-field information
transaction/change metadata
event/replay metadata

Do not assume that every event represents a complete replacement snapshot suitable for blindly overwriting a target record.

Normalize the Salesforce-specific event into an internal representation before mixing it with target-specific mapping logic.

For example:

Salesforce CDC event
        │
        ▼
Canonical change context
        ├── entity
        ├── record ID
        ├── change type
        ├── changed fields
        ├── source/event metadata
        └── relevant values
        │
        ▼
Target-specific transformation

This keeps Salesforce event semantics separate from downstream contracts.

A DataWeave Normalization Layer

The exact event structure should be validated against the connector output and the Salesforce schema used by the application, but a Mule flow can use DataWeave to create a stable internal change envelope.

Conceptually:

%dw 2.0
output application/json
---
{
    source: "salesforce",
    entity: "Account",
    recordIds: payload.ChangeEventHeader.recordIds default [],
    changeType: payload.ChangeEventHeader.changeType default null,
    changedFields: payload.ChangeEventHeader.changedFields default [],
    sourceEvent: payload
}

In a production implementation, avoid copying the complete source event into the normalized envelope unless downstream processing genuinely requires it. Select the fields required by the contract, especially when Salesforce records can contain sensitive information.

The transformation should also tolerate contract evolution deliberately rather than assuming every optional field will always be present.

CREATE, UPDATE, DELETE, and Other Change Semantics

Downstream behavior should be driven by change semantics rather than assuming every event is an update.

Conceptually:

CREATE
  └── create/upsert target representation

UPDATE
  └── apply relevant changed state

DELETE
  └── delete, deactivate, tombstone, or ignore according to domain policy

The target action is a business decision. A Salesforce deletion does not necessarily mean every downstream analytical, audit, or operational store should physically delete its representation.

Similarly, an update event may be better handled as a source re-fetch when the target needs a complete current record rather than only the event's changed fields.

Event-Carried Processing vs. Re-Fetching Salesforce

There are two important CDC consumption strategies.

Process from event data

CDC event
   │
   ▼
map event fields
   │
   ▼
update target

This preserves the state represented by the event and avoids an additional Salesforce query.

Use CDC as a trigger and re-fetch the record

CDC event
   │
   └── record ID
          │
          ▼
    query Salesforce
          │
          ▼
    current record
          │
          ▼
      update target

This can simplify mappings when the target requires a complete representation and can naturally pick up the most recent source corrections.

But the semantics are different. If multiple changes occur quickly, re-fetching may return a state newer than the particular event being processed.

Therefore decide whether the integration needs:

event-time state, or
current authoritative state.

This is the same distinction that appears in recovery replay design.

Idempotency for CDC Consumers

CDC processing should assume that the same logical work can be observed more than once because of reconnects, replay, downstream recovery, or other delivery uncertainty.

Do not use Replay ID alone as a permanent business idempotency key. It represents stream position and is intentionally opaque.

A business processing identity may incorporate source record identity together with event/change/version semantics appropriate to the integration.

For example, the consumer may track a source change identity or maintain target-side version information so an older replay cannot overwrite newer state.

The correct key depends on whether the consumer processes each change as a distinct business event or merely synchronizes the latest state of an entity.

See Designing Idempotent Integrations in Distributed Systems for the broader design patterns.

Be Careful with Out-of-Order Recovery

Consider two changes to the same Account:

change A → fails downstream
change B → succeeds downstream
change A → replayed later

If replay blindly applies the historical state from A, it may overwrite the newer state produced by B.

Possible protections include:

source change/version awareness
target optimistic concurrency
stale-event detection
serial processing by business key where ordering is required
re-fetching current Salesforce state during recovery

The correct choice depends on whether every intermediate change matters or only eventual synchronization to the current state matters.

Error Handling in the Mule Flow

Separate connector connectivity failures from business-processing failures.

A connectivity failure between MuleSoft and Salesforce concerns the subscription and reconnection strategy.

A target failure after the CDC event has been received concerns the business record.

Conceptually:

Salesforce connection problem
   └── reconnect subscription

CDC event received
   │
   ▼
processing problem
   └── retry / durable recovery / Error Hospital

Mixing these into one generic retry loop can create undesirable behavior. Reconnecting to Salesforce does not fix invalid target data, and repeatedly reprocessing a bad record does not repair a broken subscription.

For failure classification and escalation patterns, see Retry, Replay, DLQ, or Error Hospital? Choosing the Right Failure-Recovery Strategy.

Integrating CDC with an Error Hospital

When a CDC event is successfully ingested but business processing cannot complete, the failed work can enter a recovery lifecycle.

Salesforce CDC
      │
      ▼
Mule processing
      │
      ├── success ──▶ done
      │
      └── failure
             │
             ▼
        Error Hospital
             │
       remediate / wait
             │
             ▼
           replay

The recovery record does not necessarily need to retain the entire CDC payload.

For many record-synchronization integrations, retaining the Salesforce record ID plus failure context may be enough. Recovery can then query Salesforce again and process the current authoritative state.

If exact event-time reconstruction is required, retaining the appropriate event data or a protected durable reference may instead be necessary.

This should be an explicit design decision based on semantics, sensitivity, retention, and audit requirements.

Scaling the MuleSoft Consumer

Scaling an event consumer is not simply a matter of adding more runtime instances.

The chosen connector, runtime topology, ordering requirements, replay-state mechanism, and downstream concurrency all affect the safe scaling model.

For example, MuleSoft documents that when the traditional Salesforce Connector event source is deployed in a runtime cluster, the source should run on the primary node; running that source on multiple nodes can lead to duplicate consumption and corruption of connector-managed object-store replay data.

This is one reason the subscription tier and processing tier should be considered separately:

controlled Salesforce subscriber
          │
          ▼
durable internal handoff
          │
          ▼
horizontally scalable workers

Do not assume that scaling the listener itself is the best way to increase downstream throughput.

Backpressure and Downstream Limits

Salesforce may deliver changes faster than a target system can safely consume them.

The integration needs a strategy for that mismatch.

Possible controls include:

connector batch-size tuning where supported
bounded Mule concurrency
durable buffering
target-specific rate limiting
delayed retries
circuit breaking
worker scaling
replay throttling after outages

A recovered downstream system should not immediately receive an uncontrolled backlog surge.

The goal is not simply maximum throughput. It is sustainable throughput within downstream capacity.

Observability

A production CDC integration should make both subscription health and business propagation visible.

Useful signals include:

Salesforce subscription connected/disconnected state
last event received time
last safely persisted replay position
event ingestion rate
processing success/failure rate
downstream latency
retry and recovery volume
oldest unresolved failed record
duplicate/stale event detections
internal queue lag if a durable handoff is used

Also propagate correlation information so an operator can trace:

Salesforce record
      │
      ▼
CDC event
      │
      ▼
Mule processing attempt
      │
      ▼
recovery attempt if any
      │
      ▼
downstream result

Infrastructure health alone is not enough. The important question is whether Salesforce changes are reaching the required downstream systems within the expected service level.

Recovery Beyond the 72-Hour Event Window

The Salesforce event bus should not be treated as permanent recovery storage.

If the Mule application or downstream pipeline is unable to recover before required events age out of the 72-hour retention window, the architecture needs a fallback.

Depending on the integration, that may include:

querying records modified since a durable business watermark
comparing Salesforce and target state
running a reconciliation job
performing a controlled bulk resynchronization
rebuilding from an enterprise data platform if it is an authoritative retained source for the use case

This leads to a useful reliability model:

normal path      → CDC
short interruption → Replay ID
business failure → recovery lifecycle
extended gap     → reconciliation / resynchronization

No single mechanism has to solve every recovery horizon.

A Reference Architecture

A robust enterprise CDC flow can look like this:

┌──────────────────────┐
│      Salesforce      │
│ CDC-enabled objects  │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Salesforce Event Bus │
└──────────┬───────────┘
           │ replay-aware subscription
           ▼
┌──────────────────────┐
│   Mule CDC Ingestion │
│ normalize + validate │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   Durable Handoff    │  optional by workload
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Processing / Routing │
└───────┬──────┬───────┘
        │      │
        ▼      ▼
    Target A  Target B
        │
        └── failure ──▶ Recovery / Error Hospital
                           │
                           ▼
                    controlled replay

For a small integration, several boxes may collapse into one Mule flow. For a large integration platform, keeping these responsibilities separate can improve scalability and recovery control.

Implementation Checklist

Before deploying a Salesforce CDC consumer through MuleSoft, verify:

CDC is enabled only for the Salesforce entities required by the integration.
The subscription channel is intentionally entity-specific or multi-entity.
The Salesforce Connector versus Salesforce Pub/Sub Connector choice is deliberate.
The initial replay mode is appropriate for first deployment.
Replay progress is persisted when restart continuity is required.
Replay ID is treated as an opaque stream position rather than a business sequence.
Business processing is idempotent or otherwise protected against duplicate delivery.
The design distinguishes subscription recovery from failed-record recovery.
Event-time state versus current-source-state processing is explicitly chosen.
Sensitive Salesforce fields are not copied into durable messages or error stores unnecessarily.
Ordering and stale replay behavior are defined per business entity where required.
Downstream outages cannot create uncontrolled retry or replay storms.
Runtime scaling respects the connector's subscription and replay-state behavior.
The 72-hour event-retention boundary has a reconciliation strategy.
Subscription health, processing lag, failures, replay, and recovery are observable.

Closing Perspective

Consuming Salesforce CDC events from MuleSoft is easy to demonstrate: enable CDC, subscribe to /data/{Object}ChangeEvent, and process the incoming message.

Designing the integration so it remains correct through restarts, duplicate delivery, target outages, stale replay, scaling, and extended downtime requires more deliberate architecture.

The strongest design separates several concerns that are easy to confuse:

Salesforce replay position
        ≠
business processing state
        ≠
failed-record recovery state
        ≠
long-term reconciliation state

Once those boundaries are explicit, CDC becomes more than a real-time trigger. It becomes one layer of a recoverable event-driven integration architecture.