Change Data Capture Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Change Data Capture
Keep Your External Data Current with Change Data Capture
Change Event Message Structure
Merged Change Events
Other Types of Change Events: Gap and Overflow Events
Subscribe to Change Events
Change Event Storage and Delivery
Subscription Channels
Compose Streams of Change Data Capture Notifications with Custom Channels
Example Diagrams for Channels and Channel Members
Transaction-Based Replication Steps
Subscribe with Pub/Sub API
Get Compound Fields in Change Events
Enrich Change Events with Extra Fields
Filter Your Event Streams
Subscribe with Apex Triggers
Monitor Change Event Publishing and Delivery Usage
Security Considerations
Change Event Considerations
Standard Object Notes
Change Events for Fields
PDF

Subscribe with Pub/Sub API

Use Pub/Sub API to subscribe to event messages in an external client to integrate your systems. Simplify your development by using one API to publish, subscribe, and retrieve the event schema. Based on gRPC and HTTP/2, Pub/Sub API enables efficient delivery of binary event messages in the Apache Avro format. You can control the volume of event messages received per Subscribe call based on event processing speed in the client.

The Pub/Sub API service is defined in a proto file, with RPC method parameters and return types specified as protocol buffer messages. Pub/Sub API serializes the response of a Subscribe RPC call based on the protocol buffer message type specified in the proto file. For more information, see What is gRPC? and Protocol Buffers in the gRPC documentation, and pubsub_api.proto in the Pub/Sub API GitHub repository.

The Subscribe method uses bidirectional streaming, enabling the client to request more events as it consumes events. The client can control the flow of events received by setting the number of requested events in the FetchRequest parameter.

rpc Subscribe (stream FetchRequest) returns (stream FetchResponse);

Salesforce sends platform events to Pub/Sub API clients sequentially in the order they’re received. The order of event notifications is based on the replay ID of events. A client can receive a batch of events at once. The total number of events across all batches received in FetchResponses per Subscribe call is equal to the number of events the client requests. The number of events in each individual batch can vary. If the client uses a buffer for the received events, ensure that the buffer size is large enough to hold all event messages in the batch. The buffer size needed depends on the publishing rate and the event message size. We recommend you set the buffer size to 3 MB.

To learn more about the RPC methods in Pub/Sub API, see Pub/Sub API RPC Method Reference in the Pub/Sub API Developer Guide.

The channel name is case-sensitive. To subscribe to a standard channel, use this format.

/data/Channel_Name

For example, you can subscribe to all events by providing the standard ChangeEvents channel.

/data/ChangeEvents

To subscribe to a custom channel, use this format.

/data/Channel_Name__chn

For more information about channels, see Subscription Channels.

Example

After you select Opportunity for change data capture, you can subscribe to opportunity change events by supplying this channel.

/data/OpportunityChangeEvent

This example shows the fields of a change event received for a new opportunity. This example prints out the payload only. The received event message also contains the schema ID and the event ID, in addition to the payload.

{
  "ChangeEventHeader": {
    "entityName": "Opportunity",
    "recordIds": [
      "006SM0000001Tb3YAE"
    ],
    "changeType": "CREATE",
    "changeOrigin": "com/salesforce/api/soap/55.0;client=SfdcInternalAPI/",
    "transactionKey": "00000466-3d4f-bbe3-9c2b-5ab0fb45cc02",
    "sequenceNumber": 1,
    "commitTimestamp": 1652977933000,
    "commitNumber": 1652977933433528300,
    "commitUser": "005SM000000146PYAQ",
    "nulledFields": [],
    "diffFields": [],
    "changedFields": []
  },
  "AccountId": "001SM0000000iibYAA",
  "IsPrivate": null,
  "Name": "Acme - 400 Widgets",
  "Description": null,
  "StageName": "Prospecting",
  "Amount": 40000,
  "Probability": 10,
  "ExpectedRevenue": null,
  "TotalOpportunityQuantity": null,
  "CloseDate": 1653955200000,
  "Type": null,
  "NextStep": null,
  "LeadSource": null,
  "IsClosed": false,
  "IsWon": false,
  "ForecastCategory": "Pipeline",
  "ForecastCategoryName": "Pipeline",
  "CampaignId": null,
  "HasOpportunityLineItem": false,
  "Pricebook2Id": null,
  "OwnerId": "005SM000000146PYAQ",
  "CreatedDate": 1652977933000,
  "CreatedById": "005SM000000146PYAQ",
  "LastModifiedDate": 1652977933000,
  "LastModifiedById": "005SM000000146PYAQ",
  "LastStageChangeDate": null,
  "ContactId": null,
  "ContractId": null,
  "LastAmountChangedHistoryId": null,
  "LastCloseDateChangedHistoryId": null
}

Pub/Sub API is used for system integration and isn’t intended for end-user scenarios. The binary event format enables efficient delivery of lightweight messages. As a result, after decoding the event payload, some fields aren’t human readable and require additional processing. For example, CreatedDate is in Epoch time and can be converted to another date format for readability. Also, nulledFields, diffFields, and changedFields require further processing. For more information, see Event Deserialization Considerations in the Pub/Sub API Developer Guide.

The event schema is versioned—when the schema changes, the schema ID changes as well. For more information about retrieving the event schema, see Get the Event Schema with Pub/Sub API.

Write a Pub/Sub API client to subscribe to change events.