Salesforce CDC Replay IDs Explained

When consuming Salesforce Change Data Capture (CDC), one small field has an important role in reliable event processing: the Replay ID.

A Replay ID represents a position in Salesforce's event stream. A subscriber can save it and use it when reconnecting so that events still available in the retention window can be replayed.

The most important rule is simple:

Treat a Replay ID as an opaque stream position, not as a business sequence number.

Why Replay Exists

Event consumers disconnect.

A Mule application can restart, a worker can be redeployed, connectivity can fail, or maintenance can interrupt a subscription.

Without recovery information, reconnecting raises an immediate question:

Where should consumption resume?

Replay information gives the subscriber a way to communicate a position in the event stream rather than simply starting over without context.

Salesforce Retention Window

Salesforce currently retains platform events and Change Data Capture events for 72 hours on the event bus.

That means replay is a recovery mechanism within the retention window. It is not an unlimited event archive.

A design that assumes it can reconnect weeks later and replay every missed CDC event is not reliable.

If the consumer can be unavailable longer than the retention period, design another reconciliation mechanism—for example, comparing source records based on a trusted watermark or performing a controlled resynchronization.

Replay ID Is Opaque

Do not write logic that assumes Replay IDs behave like this:

1001
1002
1003
1004

Salesforce documents Replay IDs as opaque values, and consecutive events are not guaranteed to have contiguous Replay IDs.

So avoid logic such as:

expectedReplayId = previousReplayId + 1

The Replay ID is for stream positioning, not for calculating event counts or detecting missing business transactions through arithmetic.

Store the Recovery Position

A durable consumer normally needs to remember an appropriate replay position outside the transient processing context.

Conceptually:

Receive CDC event
      ↓
Process successfully
      ↓
Persist recovery position
      ↓
Receive next event

After a restart:

Read saved replay position
      ↓
Reconnect using replay behavior
      ↓
Continue processing available events

Where that state belongs depends on the runtime and reliability requirements. MuleSoft Object Store can be useful for lightweight state such as watermarks or replay information, while more complex transactional requirements may justify another persistence mechanism.

Save Progress at the Right Time

Do not advance durable recovery state before the corresponding business processing is safely complete.

A dangerous sequence is:

1. Receive event
2. Save replay position
3. Business processing fails

If the application restarts using the advanced position, the failed event may be skipped by the recovery logic.

A safer conceptual order is:

1. Receive event
2. Process required business work
3. Confirm the event is safely handled
4. Advance recovery state

Exactly what "safely handled" means depends on the architecture. It may mean the target update succeeded, or that the event was durably handed off to another reliable processing layer.

Replay Does Not Remove the Need for Idempotency

Recovery can cause an event to be delivered again.

For example, business processing might succeed but the application could fail before persisting the latest recovery position. On restart, that event can be encountered again.

Therefore:

replay capability ≠ exactly-once business processing

Consumers should be designed so that duplicate delivery does not create duplicate business effects.

Useful idempotency keys might come from event metadata or stable business identifiers, depending on the use case.

Replay ID Is Not the Salesforce Record ID

CDC messages contain information about the changed Salesforce record, but Replay ID and record identity solve different problems.

Salesforce record ID → Which business record changed?
Replay ID            → Where is this event in the stream?

Do not use Replay ID as a durable business key for an Account, Opportunity, or another Salesforce record.

Replay ID Is Not a Timestamp

Replay position also should not be treated as a replacement for business timestamps.

If you need to reason about when a business change occurred, use the event/change metadata intended for that purpose.

The Replay ID's job is stream recovery.

Recovery Beyond 72 Hours

Suppose the consumer is down for four days.

The saved Replay ID may refer to an event outside Salesforce's guaranteed retention window. At that point, replay alone is insufficient.

A resilient integration should have an answer for this scenario before production:

Replay available?
    yes → resume event processing
    no  → execute reconciliation/resynchronization strategy

Possible reconciliation approaches depend on the source and target contracts. Examples include querying records modified after a known watermark or running a bounded backfill.

Do not simply choose an arbitrary "latest" position and silently accept the missing period unless that data-loss behavior is explicitly acceptable.

MuleSoft Consumer Design

For a MuleSoft CDC consumer, think of replay as one part of a broader reliability design:

Salesforce CDC
      ↓
Mule subscriber
      ↓
validation / transformation
      ↓
idempotent business processing
      ↓
target system
      ↓
advance durable recovery state

Then separately define:

• retry behavior;
• poison-message handling;
• duplicate handling;
• replay-position persistence;
• reconciliation after retention expires;
• monitoring for consumer lag or prolonged downtime.

Quick Rules

Remember these five points:

1. Replay IDs represent positions in the Salesforce event stream.
2. Treat Replay IDs as opaque values; do not perform sequence arithmetic on them.
3. Salesforce guarantees CDC/platform-event retention for 72 hours, not indefinitely.
4. Advance durable recovery state only after the event is safely handled.
5. Replay and idempotency solve different reliability problems—you usually need both.

Practical Rule

Replay IDs answer where should my event consumer resume?

They do not answer did my business operation happen exactly once?

Keeping those responsibilities separate leads to much safer CDC integrations.