Change Data Capture
Change Data Capture (CDC) is a Salesforce streaming feature that publishes change events (create, update, delete, undelete) for selected objects to the event bus in near real time.
Definition
Change Data Capture (CDC) is a Salesforce streaming feature that publishes change events (create, update, delete, undelete) for selected objects to the event bus in near real time. External systems subscribe to these events to replicate Salesforce data, trigger downstream automation, or feed analytics pipelines without polling the REST API for changes. CDC events look similar to Platform Events but carry the full record state alongside the change metadata.
CDC is the foundation of modern Salesforce-to-external-system synchronization patterns. Where the older approach was to poll Salesforce on a schedule for records modified since the last run, CDC pushes changes to subscribers as they happen. The latency drops from minutes (or hours) to seconds. The platform handles ordering, replay, and partitioning automatically. Subscribers consume CDC through CometD (legacy) or the Pub/Sub API (modern), and the same event bus that powers Platform Events also delivers CDC events. The two are siblings architecturally but different in purpose: CDC tracks record changes, Platform Events represent business actions.
How Change Data Capture streams record changes from Salesforce
Selecting which objects to publish
CDC is opt-in per object. Setup > Change Data Capture > select objects > Save. Each org has an entitlement for the number of objects (typically 5 for standard editions, more with the Data Pipelines add-on). Standard objects (Account, Contact, Opportunity, Case, Lead) plus most custom objects are supported. Knowledge, BigObjects, and a few other specialized objects are not. Pick objects deliberately because changing the set later loses in-flight subscription state.
Event structure and payload
Each CDC event contains the header (changeType: CREATE, UPDATE, DELETE, UNDELETE, GAP_OVERFLOW), the record ID, the changed field values, and the change origin (user ID, source channel). The payload represents the new state of the record after the change. For updates, only the changed fields appear; unchanged fields are not retransmitted. Subscribers reconstruct the full record state by combining the CDC payload with their local cache, or by querying the REST API for the complete record when needed.
Subscribers: external systems and Apex triggers
External systems subscribe via CometD streaming or the Pub/Sub API (gRPC, the modern path). Each subscriber gets every event for the selected objects, with replay support for offline windows. In-org subscribers can be Apex triggers on the corresponding ChangeEvent object: trigger AccountCDC on AccountChangeEvent (after insert) { ... }. Apex CDC triggers process events asynchronously, outside the original transaction, which is useful for non-blocking follow-up work.
Replay, gap overflow, and retention
Every CDC event has a replayId. Subscribers persist the replayId of the last processed event so they can resume from that point after reconnection. The platform retains CDC events for up to 72 hours; subscribers offline longer than that lose events with no recovery. A GAP_OVERFLOW event indicates the subscriber fell too far behind and missed events permanently. Plan subscriber availability and monitoring so disconnections do not produce data loss; for critical replication, build a reconciliation job that compares Salesforce state against the downstream system periodically.
Order of execution and transaction semantics
CDC events publish after the originating transaction commits. If the transaction rolls back, no event publishes. Multiple changes within one transaction (a trigger that updates multiple records, a Flow that creates a parent and several children) produce multiple events. The order matters for downstream replication: events for the same record arrive in time order, but events across different records may interleave. Plan replication logic to handle out-of-order arrival across records.
Performance, throughput, and daily limits
CDC scales to tens of thousands of events per second on the platform side, but each org has a daily event allocation. Setup > Platform Event Usage shows current consumption. Excessive event volumes can throttle or exceed the cap, dropping events silently. Plan event volume based on actual change rates on the selected objects; selecting Account and Contact when both have millions of daily updates produces very large event streams that may exceed the entitlement.
CDC versus Platform Events versus Salesforce Streaming
Three related streaming features. Platform Events publish business events explicitly through code or declarative tools; subscribers react. CDC publishes record change events automatically when records change; no code needed to publish. Generic Streaming pushes custom events from external systems; less commonly used today. CDC is the right tool for replicating Salesforce data; Platform Events are the right tool for business events that do not map cleanly to record changes; Generic Streaming is a legacy fallback rarely chosen for new work.
How to set up Change Data Capture
Enabling CDC is a one-click toggle per object. The harder work is on the subscriber side: building the Pub/Sub or CometD client, handling replay, processing events idempotently. Plan the subscriber architecture before enabling CDC because once events start flowing, downstream systems need to consume them or events expire on the bus.
- Identify which objects need change tracking
List the Salesforce objects whose changes external systems need to consume. Account, Contact, Opportunity are common. Custom objects supporting integrations also fit. Each org has a limit on the number of objects, so choose deliberately.
- Enable CDC in Setup
Setup > Change Data Capture > Select Entities. Pick the objects, save. Events start flowing immediately. The Change Event Allocations section shows the daily allocation and current consumption.
- Build the subscriber via Pub/Sub API
The modern subscriber pattern uses the gRPC-based Pub/Sub API. Build a client in your language of choice with the published proto files. Subscribe to the appropriate ChangeEvent topic, process events, and persist the last successful replayId.
- Handle replay correctly
On reconnection, resume from the last persisted replayId. Without replay state, the subscriber starts from now and misses events that arrived during the offline window. Build replay handling as a first-class feature, not an afterthought.
- Process events idempotently
Subscribers may receive the same event multiple times due to retries. Build idempotent processing: check whether the downstream system has already applied the event, skip duplicates. The replayId is a natural deduplication key.
- Build the in-org Apex subscriber if needed
For in-org reactions to CDC events, write an Apex trigger on the ChangeEvent object: trigger AccountCDCHandler on AccountChangeEvent (after insert). The trigger fires asynchronously when events arrive.
- Add monitoring for gap overflow and disconnections
Build alerts on GAP_OVERFLOW events (subscriber fell behind) and on subscriber disconnection duration. Both indicate replication problems that need investigation before downstream data drifts.
- Build reconciliation for critical replication
For replication that must stay accurate, run a periodic reconciliation: compare Salesforce record counts and timestamps against the downstream system. Catch divergences early before they accumulate.
Which objects publish change events. Limited by entitlement; select based on actual integration needs.
Pub/Sub API (gRPC, modern) or CometD (long-polling, legacy). Pub/Sub is the strategic direction for new integrations.
Persist the last successful replayId. On reconnection, resume from that point. Without replay, offline events are lost permanently.
- CDC events retain for 72 hours. Subscribers offline longer than that lose events permanently. Critical replication needs reconciliation jobs to detect and recover.
- GAP_OVERFLOW events indicate the subscriber fell behind. The platform skips events to catch up. Build alerting on this event type and triage the cause before data diverges.
- Daily event allocations cap CDC throughput. Excessive change volume on selected objects can exceed the cap, dropping events silently. Monitor Platform Event Usage daily.
- Events publish after transaction commit. Rolled-back transactions produce no events. Subscribers should not assume a CDC event always indicates a permanent state change visible immediately to other queries.
- Only changed fields appear in CDC payloads. Subscribers reconstruct full record state by combining payload with cache or by querying the REST API for the complete record.
Trust & references
Cross-checked against the following references.
- Change Data Capture OverviewSalesforce Developer
- CDC Event FieldsSalesforce Developer
Straight from the source - Salesforce's reference material on Change Data Capture.
- CDC Developer GuideSalesforce Developer
- Subscribe to CDC with ApexSalesforce Developer
- CDC Event AllocationsSalesforce Developer
Hands-on resources to go deeper on Change Data Capture.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does Change Data Capture publish?
Q2. What is a key benefit of CDC over API polling?
Q3. What are Change Event triggers in Apex?
Discussion
Loading discussion…