Salesforce Change Data Capture sends record-change events to an external subscriber, so your SaaS can react without repeatedly polling Salesforce. Setup requires enabling objects, authorizing a subscriber, and processing events with durable recovery.
However, receiving an event doesn’t prove that your integration applied it correctly. Start with a narrow object selection, then build authentication, replay, and reconciliation around the records your application needs.
Key Takeaways
- Enable CDC for supported objects, then subscribe through Pub/Sub API or Streaming API.
- Authorize a dedicated integration identity and isolate each customer’s data and replay position.
- Treat events as change notifications, not complete records or historical backups.
- Test duplicate delivery, deletes, expired replay positions, and schema changes before production rollout.
Enable Salesforce Change Data Capture for Selected Objects
Define the records your integration needs
CDC publishes notifications for record creation, updates, deletion, and undeletion. It supports all custom objects and a subset of standard objects.
Start with one business workflow. For example, subscribing to Account changes can keep customer details synchronized with your SaaS. Add Opportunity only when your integration needs deal changes.
Salesforce’s CDC allocation documentation sets the default selection limit at five entities. An eligible add-on can expand that allowance. Selecting the same entity in multiple channels counts once toward the default limit.
Enable the selected objects
Viewing the configuration requires View Setup and Configuration. Changing object selections requires Customize Application.
- Open Setup, enter
Change Data Capturein Quick Find, and open the matching page. - Select the supported objects your integration needs and move them into the selected list.
- Save the selection.
These are required Salesforce configuration steps. Creating destination mappings, documenting field ownership, and testing in a sandbox are recommended integration practices.
Enabling CDC doesn’t create a subscriber, authorize your SaaS, or transfer existing records. Those are separate tasks.
Configure and Authorize the Subscriber
Establish OAuth authentication
For a new integration, configure an external client app for the chosen OAuth flow. An existing, authorized connected app can also support an established integration.
Request the OAuth api scope. For unattended processing, use a supported server-to-server flow, such as client credentials or JWT bearer, rather than an employee’s interactive session.
Authorize a dedicated integration user with API Enabled and the permissions required to receive the selected change events. CDC subscription access requires object-level View All Records or the broader View All Data permission.
Prefer object-scoped access when it meets the integration’s requirements.
Connect with the correct tenant context
Pub/Sub API requires the Salesforce access token, instance URL, and organization ID in gRPC request metadata. Their metadata keys are accesstoken, instanceurl, and tenantid.
Store credentials in a secrets manager and renew expired tokens through your OAuth flow.
For a multi-tenant SaaS, keep credentials, subscriptions, queues, and replay checkpoints separate for each Salesforce organization. Also enforce tenant ownership when writing destination records.
CDC ignores record-sharing rules. Therefore, don’t assume the integration user’s normal Salesforce page visibility limits the records arriving through the event stream.
Choose an API and Consume Change Events
Use the appropriate subscription interface
Pub/Sub API uses gRPC over HTTP/2 and Apache Avro payloads. Its bidirectional Subscribe RPC lets your client request events according to available processing capacity.
Streaming API is another option, using CometD and Bayeux. REST API and Bulk API are useful for record queries and baseline exports; they don’t replace a CDC subscription.
Salesforce also documents managed event subscriptions, currently labeled Beta, which manage replay state server-side. Standard Subscribe requires your application to maintain its own checkpoint.
For automation builders, connector support matters: a generic webhook trigger can’t accept a gRPC event stream. Your middleware must support the subscription protocol.
Select a channel and decode the payload
Use /data/AccountChangeEvent for Account events or /data/OpportunityChangeEvent for Opportunity events. For a custom object such as Invoice__c, the channel is /data/Invoice__ChangeEvent.
The /data/ChangeEvents channel combines events for selected entities. Channel names are case-sensitive.
With Pub/Sub API, retrieve the schema identified by the event’s schema ID through GetSchema, then decode the Avro payload.
Read ChangeEventHeader, including changeType, recordIds, transactionKey, and sequenceNumber. Process every ID in recordIds; one event can reference multiple records.
For updates, apply only the changed fields. Distinguish an unchanged field from one explicitly cleared to null. Decode changedFields and nulledFields bitmaps against the matching schema instead of treating every decoded value as a replacement.
Build Replay and Initial Synchronization Together
Load existing records without leaving a gap
Salesforce Change Data Capture starts with changes, so an existing customer database needs a separate initial load.
A practical approach is to start a subscription and durably buffer incoming events before exporting the baseline. Load existing records through REST API or Bulk API 2.0, then apply buffered changes through the same idempotent processing path.
Use Salesforce record IDs as stable source identifiers, qualified by organization and object in your SaaS.
Document which system owns each synchronized field. Otherwise, a Salesforce update and a product-side update can repeatedly overwrite each other. If your SaaS writes back to Salesforce, define how it recognizes its own changes and prevents synchronization loops.
Save checkpoints after durable processing
LATEST starts with new events. EARLIEST starts with the earliest retained events. CUSTOM resumes after a supplied replay ID.
Replay IDs are opaque bytes. Preserve them losslessly, and never increment them or treat them as Salesforce record identifiers.
Salesforce’s event durability guidance describes the 72-hour retention window. Older events can sometimes remain available, but recovery must not depend on that.
Advancing a checkpoint before durable storage can turn a temporary worker failure into a permanently skipped update.
Persist the checkpoint after applying the event or placing it in a durable queue. Expect redelivery, and make destination updates idempotent. If the saved position is no longer available, reconcile against Salesforce records and establish a new baseline.
Handle Deletes and Schema Changes Explicitly
Process deletes through the event header
A delete event has empty record and system-field values. Use changeType and recordIds to identify the affected records.
Choose a destination policy before launch. Your SaaS might remove the synchronized row or retain a tombstone that marks it deleted. The right choice depends on reporting, privacy, and relationship requirements.
Hard deletion from Salesforce’s Recycle Bin doesn’t generate another change event. Therefore, don’t wait for a second notification before applying the original deletion policy.
Also handle UNDELETE. If your destination discarded the record’s attributes, retrieve its current values before restoring it. Keep deletion handling idempotent so repeated events don’t cause failures or duplicate downstream actions.
Decode with the event’s actual schema
Cache Avro schemas by schema ID. When an event references an unfamiliar ID, fetch that schema before decoding the payload.
Then keep decoding separate from business mapping. A new field shouldn’t break processing when your application doesn’t use it. However, a removed field or incompatible type change may require a mapping update.
Maintain a short data dictionary covering source field, destination field, type, owner, and null behavior. Include schema updates in your release process rather than allowing production messages to introduce unreviewed mappings.
Oversized events also need a recovery path. Salesforce limits published event messages to 1 MB and replaces an oversized event with a gap event. Treat that notification as a reconciliation task, not a complete record update.
Plan for Limits and Prove the Integration Works
External event delivery uses a rolling 24-hour allocation shared across Pub/Sub API, CometD, Lightning empApi, and event relays.
The documented default CDC delivery allocations differ by edition.
| Salesforce edition | Default deliveries per 24 hours |
|---|---|
| Enterprise | 25,000 |
| Performance and Unlimited | 50,000 |
| Developer | 10,000 |
These are delivery allocations, so multiple subscribers increase consumption. Salesforce’s CDC integration guidance also identifies concurrent-client limits as a consideration for architectures with many subscribers.
For a SaaS, one ingestion service per organization with internal distribution often makes operations simpler than separate Salesforce subscriptions for every downstream feature.
Before rollout, exercise create, update, explicit null, delete, and undelete paths. Then interrupt the subscriber and prove that it resumes without losing changes or repeating business actions.
Record the Salesforce organization, record IDs, event timestamp, processing result, and destination outcome for each test. Use representative non-admin permissions because an administrator session can hide access problems.
Also test token expiration, destination outages, unfamiliar schemas, and an unavailable replay position. Approve rollout only when missing or unexpected destination rows have an explanation.
After launch, monitor processing lag, queue depth, failed writes, authentication failures, and allocation consumption. Assign an owner for reconciliation and connection failures. A connected subscriber alone doesn’t prove that customer data is synchronized.
Frequently Asked Questions
Is Salesforce CDC a webhook?
No. CDC publishes events to Salesforce subscription channels. Pub/Sub API uses gRPC, while Streaming API uses CometD.
To deliver HTTP webhooks to another service, your subscriber or middleware must receive the Salesforce events and make those HTTP requests. That additional delivery path needs its own retry and idempotency handling.
Does every activity on a Salesforce timeline produce CDC events?
No. Timeline visibility doesn’t establish that an interaction exists as a supported Salesforce object record.
Einstein Activity Capture can display captured activity whose storage differs from core Salesforce records. Build CDC around supported record objects and their actual storage path, rather than assuming every visible email or calendar interaction is available through the change stream.
Make Recovery Part of the Setup
A dependable Salesforce Change Data Capture integration combines object selection and authorization with recoverable processing. Replay checkpoints, explicit delete handling, and schema-aware decoding protect the destination when connections or mappings fail.
Start with one object and prove the complete path through a controlled outage. Expand only after your team can explain both successful updates and reconciliation results.
