Subscribe to Platform Event Notifications 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.

1rpc 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 platform event channel name is case-sensitive. To subscribe to an event, use this format.

1/event/Event_Name__e

To subscribe to a custom channel, use this format.

1/event/Channel_Name__chn

Example

If you have a platform event named Low Ink, provide this channel name when subscribing.

1/event/Low_Ink__e

This example shows the fields in the payload of the received event message. 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.

1{
2  "CreatedDate": 1652978695951,
3  "CreatedById": "005SM000000146PYAQ",
4  "Printer_Model__c": "XZO-5",
5  "Serial_Number__c": "12345",
6  "Ink_Percentage__c": 0.2
7}

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.

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 platform event messages. You can use one of the 11 supported programming languages, including Python, Java, Go, and Node.