Subscribe to Change Events

You subscribe to change events with CometD or Apex triggers. CometD is a messaging library that enables listening to events through long polling and simulates push technology. Apex triggers for change events are similar to Apex triggers on platform events.

The Event Bus

Change events are based on platform events and share some of their characteristics. Change event messages are published to the event bus, where they are stored temporarily for three days. You can retrieve stored event messages from the event bus. Each event message contains the ReplayId field, which identifies the event in the stream and enables replaying the stream after a specific event. For more information, see Message Durability in the Streaming API Developer Guide.

Order of Events

The order of change events stored in the event bus corresponds to the order in which the transactions corresponding to the record changes are committed in Salesforce. If a transaction includes multiple changes, like a lead conversion, a change event is generated for each change with the same transactionKey but different sequenceNumber in the header. The sequenceNumber is the order of the change within the transaction. For efficiency, sometimes change events for one transaction are grouped into one event if the same change occurred in multiple records of the same object type during one second. For example, when an account field is updated to the same value across multiple records in a short time. In this case, the recordIds header field contains an array of record IDs for all records that have the same change. For more information, see Change Event Header Fields.

When Salesforce receives a change event, it assigns a replay ID value to it and persists it in the event bus. Subscribers receive change events from the event bus in the order of the replay ID.

User Permissions Required

The subscriber must have one or more of the following permissions depending on the subscription channel: View All Data, View All Users, and View All for an object. See Required Permissions for Change Events Received by CometD Subscribers.

Subscription Channels
A subscription channel is a stream of change events that correspond to one or more entities. You can subscribe to the channel to receive change event notifications for record create, update, delete, and undelete operations. Change Data Capture provides predefined standard channels and you can create your own custom channels. Use the subscription channel that corresponds to the change events you want to receive. The channel name is case-sensitive.
Compose Streams of Change Data Capture Notifications with Custom Channels
Create a custom channel if you have multiple subscribers and each subscriber receives change events from a different set of entities. Also, use a custom channel with event enrichment (beta) to isolate sending enriched fields in change events on a specific channel. Custom channels group and isolate change events for each subscriber so subscribers receive only the types of events they need.
Example Diagrams for Channels and Channel Members
Discover the relationship between channels, channel members, and enriched fields (beta) with the Entity Relationship Diagram (ERD). Also, understand the benefits of using custom channels through the example diagrams.
Subscribe with CometD Using the EMP Connector Sample
Salesforce provides a connector to CometD that subscribes to streaming events. The EMP connector sample is a thin wrapper around the CometD library and simplifies subscribing to data change events in Java. The tool subscribes to a channel, receives notifications, and supports replaying events with durable streaming.
Enrich Change Events with Extra Fields When Subscribed with CometD (Beta)
Change event messages include values for new and changed fields, but sometimes unchanged field values are needed for processing or replicating data. For example, a replication app needs an external ID field to match the record in an external system. You can select which fields to always include in change event messages when those fields are non-empty.
Subscribe with Apex Triggers
With Apex triggers, you can capture and process change events on the Lightning Platform. Change event triggers run asynchronously after the database transaction is completed. Perform resource-intensive business logic asynchronously in the change event trigger, and implement transaction-based logic in the Apex object trigger. By decoupling the processing of changes, change event triggers can help reduce transaction processing time.
High-Level Replication Steps
To maintain an accurate replica of your org’s data in another system, subscribe using a transaction-based approach.

Change Data Capture Developer Guide

Subscribe to Change Events

The Event Bus

Order of Events

User Permissions Required

See Also