Change Data Capture Apex

Change Data Capture Apex

Use this skill when implementing or reviewing Apex logic that subscribes to Salesforce record change events via CDC triggers. CDC triggers fire asynchronously after DML commits and provide rich header metadata (changeType, changedFields, recordIds, commitUser) for precise, efficient processing. This skill covers the complete Apex-side CDC pattern: trigger declaration, header field access, change-type routing, gap event handling, field-level filtering, and entity configuration.

Before Starting

Gather this context before working on anything in this domain:

• Is the object enabled for CDC? Go to Setup > Integrations > Change Data Capture. The object must be selected there — the trigger compiles but fires no events if the object is not tracked.
• Is this a platform event? If the event is manually published by application code (e.g., EventBus.publish()), use apex/platform-events-apex instead. CDC events are system-generated; they cannot be manually published.
• What operations need handling? CDC triggers fire for CREATE, UPDATE, DELETE, and UNDELETE. Confirm which change types the business logic must react to — GAP events also require handling in production.
• Is synchronous callout needed? CDC triggers run asynchronously under the Automated Process entity. Synchronous callouts from a CDC trigger are not supported. Use a queueable or @future(callout=true) dispatched from the trigger if callouts are required.
• Batch size: Default maximum is 2,000 event messages per trigger invocation. Override with PlatformEventSubscriberConfig if needed.

Core Concepts

CDC Trigger Syntax and Execution Model

A CDC trigger is always an after insert trigger on the change event object — not on the base sObject. The change event type name follows the pattern <ObjectApiName>ChangeEvent for standard objects and <ObjectApiName>__ChangeEvent for custom objects.

trigger AccountChangeEventTrigger on AccountChangeEvent (after insert) {
    // Trigger.new contains up to 2,000 AccountChangeEvent records per batch
}

CDC triggers:

• Execute asynchronously after the originating database transaction commits. They run outside the originating Apex transaction.
• Run under the Automated Process entity, not the user who performed the DML. Debug logs must be configured for the Automated Process entity — they do not appear in the Developer Console log tab by default.
• Are subject to synchronous Apex governor limits despite running asynchronously. SOQL, DML, CPU, and heap limits apply per invocation just as in synchronous Apex.
• Have a maximum batch size of 2,000 event messages per execution. Multiple batches fire if more events are queued.
• Can be configured with PlatformEventSubscriberConfig (Tooling API or Metadata API) to override the running user identity and default batch size.

ChangeEventHeader and Header Fields

Every event in Trigger.new exposes a ChangeEventHeader field (type EventBus.ChangeEventHeader) that carries all change metadata. Access it via the event's .ChangeEventHeader property.

Key header fields for Apex:

changedFields and nulledFields are available in Apex triggers and Pub/Sub API only — they are absent in CometD subscribers. This is the primary reason to prefer Apex triggers when the subscriber must perform field-level filtering.

Access record IDs via the method header.getRecordIds() which returns a List<String>.

Change Event Body Fields in Apex

In an Apex CDC trigger, all record fields are present on the event object whether or not they changed. Unchanged fields are null in the event message. This is different from external CDC consumers where the full record is returned for a CREATE but only changed fields are populated for UPDATE. Do not read an unchanged field and assume its value is current — use changedFields to determine which fields actually changed, then query the record for full state if needed.

Entity Tracking and GAP Events

CDC must be explicitly enabled per object. For standard channels, enable in Setup > Integrations > Change Data Capture. The default limit is 5 entities across all channels and editions without the CDC add-on. Custom objects count toward this limit.

When Salesforce cannot generate a full change event (event exceeds 1 MB, large bulk operation bypasses the application server, internal error), it generates a gap event with a changeType prefixed by GAP_: GAP_CREATE, GAP_UPDATE, GAP_DELETE, GAP_UNDELETE, or GAP_OVERFLOW. Gap events carry recordIds but no field values. Apex code that does not check for gap events will attempt to process null field bodies and silently miss changes.

The ALL_CHANGE_EVENTS channel and AllChangeEvents event type require the ReceiveAllChangeEvents org permission and are typically restricted to system integration use.

Note: CDC triggers cannot subscribe to multi-entity channels. An Apex trigger is always bound to a single change event type (e.g., AccountChangeEvent). There is no equivalent of subscribing to /data/ChangeEvents in Apex.

Common Patterns

Pattern 1: Field-Selective UPDATE Processing

When to use: The trigger should only react when specific fields change (e.g., Status__c, OwnerId) rather than on any update.

How it works:

trigger CaseChangeEventTrigger on CaseChangeEvent (after insert) {
    List<Id> casesWithStatusChange = new List<Id>();

    for (CaseChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;

        // Skip non-UPDATE events
        if (header.changeType != 'UPDATE') {
            continue;
        }

        // Only act when Status field is in changedFields
        if (header.changedFields.contains('Status')) {
            casesWithStatusChange.addAll((List<Id>) header.getRecordIds());
        }
    }

    if (!casesWithStatusChange.isEmpty()) {
        // Query for full current state — do not rely on event field values for UPDATE
        List<Case> cases = [SELECT Id, Status, OwnerId FROM Case WHERE Id IN :casesWithStatusChange];
        CaseStatusHandler.process(cases);
    }
}

Why not just read the field from the event: For UPDATE events, unchanged fields are null in the event body. Reading event.Status when Status did not change returns null, not the current value. Always use changedFields to filter, then query the record for current state.

Pattern 2: Change-Type Routing with GAP Handling

When to use: The trigger must handle all four operation types (CREATE, UPDATE, DELETE, UNDELETE) with distinct logic per type, and must be resilient to gap events.

How it works:

trigger AccountChangeEventTrigger on AccountChangeEvent (after insert) {
    List<Id> createdIds    = new List<Id>();
    List<Id> updatedIds    = new List<Id>();
    List<Id> deletedIds    = new List<Id>();
    List<Id> undeletedIds  = new List<Id>();
    List<Id> gapIds        = new List<Id>();

    for (AccountChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
        List<String> ids = header.getRecordIds();

        if (header.changeType == 'CREATE') {
            createdIds.addAll((List<Id>) ids);
        } else if (header.changeType == 'UPDATE') {
            updatedIds.addAll((List<Id>) ids);
        } else if (header.changeType == 'DELETE') {
            deletedIds.addAll((List<Id>) ids);
        } else if (header.changeType == 'UNDELETE') {
            undeletedIds.addAll((List<Id>) ids);
        } else if (header.changeType.startsWith('GAP_')) {
            // Gap event: no field values available — mark dirty for re-sync
            gapIds.addAll((List<Id>) ids);
        }
    }

    // Dispatch to handlers
    if (!createdIds.isEmpty())   AccountSyncHandler.handleCreate(createdIds);
    if (!updatedIds.isEmpty())   AccountSyncHandler.handleUpdate(updatedIds);
    if (!deletedIds.isEmpty())   AccountSyncHandler.handleDelete(deletedIds);
    if (!undeletedIds.isEmpty()) AccountSyncHandler.handleUndelete(undeletedIds);
    if (!gapIds.isEmpty())       AccountSyncHandler.handleGap(gapIds);
}

Why not just check for UPDATE: Failing to handle GAP events means silent data drift when events cannot be generated at full fidelity. Always check changeType.startsWith('GAP_') as a catch-all.

Pattern 3: Multi-Record Batch Processing with getRecordIds

When to use: A single change event can contain multiple record IDs when Salesforce merges identical changes (e.g., a bulk update of the same field on many records). Always iterate getRecordIds() rather than assuming a 1:1 event-to-record relationship.

How it works:

trigger ContactChangeEventTrigger on ContactChangeEvent (after insert) {
    Set<Id> affectedContacts = new Set<Id>();

    for (ContactChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
        // getRecordIds() returns List<String>; cast to Id after collecting
        affectedContacts.addAll((List<Id>) header.getRecordIds());
    }

    // Single SOQL for the entire batch
    if (!affectedContacts.isEmpty()) {
        List<Contact> contacts = [
            SELECT Id, AccountId, Email, Status__c
            FROM Contact
            WHERE Id IN :affectedContacts
        ];
        ContactIntegrationHandler.process(contacts);
    }
}

Why not iterate Trigger.new directly: Each Trigger.new record is an event, but one event can represent changes to multiple records. Iterating events without collecting all recordIds will process the batch incorrectly. Pattern: collect all IDs across the batch, then issue a single SOQL.

Decision Guidance

Recommended Workflow

1. Confirm entity tracking — Verify the target object is enabled in Setup > Integrations > Change Data Capture. Confirm the 5-entity limit is not exceeded without the add-on. For custom objects, confirm the correct change event API name (<ObjectName>__ChangeEvent).

2. Define which change types require handling — Identify whether CREATE, UPDATE, DELETE, UNDELETE, and/or GAP events each need distinct logic. If the use case is UPDATE-only with field filtering, identify the specific fields whose changes should trigger action.

3. Write the trigger skeleton — Use trigger <Name> on <ChangeEventType> (after insert). Never use before insert or any other trigger event — CDC triggers only support after insert.

4. Implement header access and change-type routing — Access event.ChangeEventHeader for each event. Use changeType to route to per-operation handlers. Always include a GAP_ branch that marks records dirty or queues a re-fetch.

5. Implement field-level filtering for UPDATE events — For UPDATE branches, check header.changedFields before processing. Query the record for full current state — do not read field values directly from the event body for UPDATE events, as unchanged fields are null.

6. Collect all record IDs using getRecordIds() — Accumulate IDs across all events in the batch using a Set<Id>. Issue a single bulk SOQL query outside the loop to retrieve current record state.

7. Set up debug logging and test — Configure a trace flag for the Automated Process entity. Write unit tests using Test.getEventBus().deliver() to verify all change-type branches, changedFields filtering, and GAP event handling.

Review Checklist

• Trigger is declared as after insert on the change event type (not the base sObject).
• Object is enabled in Setup > Change Data Capture before deploying trigger.
• All relevant changeType values are handled: CREATE, UPDATE, DELETE, UNDELETE, and GAP events.
• changedFields is checked before processing UPDATE events to avoid reacting to unrelated field changes.
• Record IDs are collected via header.getRecordIds() — not assumed to be one record per event.
• Record state is retrieved via SOQL query for UPDATE processing — event field values are not used directly for changed fields (unchanged fields are null).
• No synchronous callouts in the trigger body; callouts dispatched to @future(callout=true) or Queueable.
• Batch-safe SOQL and DML: all queries and DML operate on collected Sets/Lists, not inside the event loop.
• Debug logs configured for the Automated Process entity.
• Unit tests cover all change-type branches including GAP, using Test.getEventBus().deliver().

Salesforce-Specific Gotchas

1. CDC triggers run under Automated Process — not the current user — Debug logs created by the trigger execution are attributed to the Automated Process entity, not the DML-performing user. Logs will not appear in the Developer Console log tab unless a trace flag is set for Automated Process in Setup > Debug Logs. Developers who look in the wrong place will conclude the trigger is not firing when it is.

2. Unchanged fields are null in UPDATE event body — For an UPDATE change event in Apex, fields that were not changed in the triggering DML are null on the event object. Reading event.BillingCity when BillingCity was not updated returns null — it does not return the current field value. Only changedFields reliably identifies what changed. Always query the record for full state rather than reading fields directly from UPDATE event bodies.

3. Apex CDC triggers cannot subscribe to multi-entity channels — An Apex trigger is bound to exactly one change event type. There is no way to write a single Apex trigger that handles AccountChangeEvent and ContactChangeEvent. Unlike external subscribers that can subscribe to /data/ChangeEvents, Apex triggers require one trigger file per tracked entity. Architects expecting a "catch-all" Apex subscriber will need one trigger per object.

4. GAP events carry no field values — A gap event fires when the full change event cannot be generated (event too large, bulk bypass, internal error). The event body is empty; only recordIds and the GAP-prefixed changeType are available. Apex code that skips the GAP check and falls through to field access will read null fields and silently skip the change. Production CDC subscribers must include explicit GAP handling that queues a record re-fetch.

5. CDC triggers are subject to synchronous governor limits — Despite running asynchronously, CDC triggers consume Apex synchronous limits (100 SOQL, 150 DML operations, 10 MB heap) per batch invocation. A batch of 2,000 events that naively issues one SOQL per event will hit the 100-SOQL limit. Always collect IDs across the full Trigger.new loop and issue bulk SOQL outside the loop.

Output Artifacts

Related Skills

• integration/change-data-capture-integration — Use when the CDC subscriber is an external system (MuleSoft, Kafka, custom gRPC client) connecting via CometD or Pub/Sub API.
• apex/platform-events-apex — Use when publishing or subscribing to custom Platform Events from Apex; also covers EventBus.publish() patterns.
• architect/platform-selection-guidance — Use when deciding between CDC, Platform Events, outbound messaging, and polling for an integration or automation pattern.