Update July 6, 2022: Pub/Sub API is now Generally Available! Learn more in this announcement post and our developer guide.

A new way to publish and subscribe to events is coming: the Pub/Sub API pilot is launching in Summer 2021. These events could be Platform Events, Change Data Capture events, and/or Real-Time Event Monitoring events. The Pub/Sub API arrives hand-in-hand with the new Event Bus Runtime, a modern piece of behind-the-scenes infrastructure that will allow all Salesforce customers to scale to greater heights than ever before. Read more about the new runtime in this Salesforce Architects blog post.

What is new about the Pub/Sub API?

To make event-driven integrations today, customers have a few different options for publishing: they can use the Bulk API, SOAP API, or REST API. These APIs allow developers to publish any standard Platform Event that supports the create() call (e.g. CommerceDiagnosticEvent) and/or any custom Platform Event. To subscribe to events, customers can use the Streaming API, which allows them to subscribe to any Change Data Capture event, Platform Event, or Real-Time Event Monitoring event.

With the new Pub/Sub API, all that functionality is consolidated into one comprehensive API. The Pub/Sub API allows users to publish events, subscribe to events, request schema, and request topic information all within one API. It eradicates the need for building out a custom CometD Streaming API client — something that is not always easy for developers without prior CometD experience or knowledge. Without the need for a custom CometD client, more users can start implementing event-driven frameworks in their architecture than ever before. The Pub/Sub API also has improved built-in logic for flow control and publish acknowledgments, allowing developers to create more robust applications than they could with the Streaming API.

The Pub/Sub API can help you streamline your integration architecture and tackle projects like:

• Subscribing to Event Monitoring events and publishing a Platform Event back into Salesforce to restrict a user’s profile when they log into Salesforce after working hours
• Subscribing to Change Data Capture events and replicating order data in an external inventory system
• Subscribing to a standard Platform Event like AppointmentSchedulingEvent and integrating with Google Calendar to update users’ calendars

What is gRPC?

Many of the added benefits of the Pub/Sub API come from the fact that it is a gRPC-based API, the first of its kind to be offered by Salesforce. gRPC is a new industry-leading enterprise API protocol that boasts a host of improvements over REST and SOAP:

• Better performance: gRPC is about seven to ten times faster than REST due to the fact that its payload format is compressed, lightweight byte buffers instead of JSON.
• Bidirectional streaming: Unlike the unary request-response paradigm employed by REST and SOAP, gRPC allows for clients and servers to set up and maintain open bidirectional communication channels between them. This enables both a client and a server to operate independently, meaning that a client can consume and publish events in any order it wishes. In addition, gRPC preserves the order of messages within the stream.
• Built on HTTP 2: This new standard guarantees better performance, increased security, and lower overhead compared to APIs built on HTTP 1.

gRPC is officially supported in 11 languages and has unofficial community support in more, empowering developers with any mainstream programming background to make full use of the Pub/Sub API’s abilities. It also boasts an active online developer community, which will make developing with gRPC much smoother sailing than building out a CometD client.

How to use a proto file

Part of gRPC’s conceptual difference from REST and SOAP is that it exposes remote procedure calls (RPCs) instead of endpoints. These RPCs are methods that can be called remotely with specified parameters and return types. The API server implements this interface and runs a gRPC server to handle client calls. The client has a stub that mirrors the methods available on the server. All of these methods, or RPCs, are defined in a “proto file,” which contains all the RPC method parameters and return types specified as protocol buffer messages. The Pub/Sub API proto file can be found in the Salesforce Pub/Sub API repo on Github. The following is a snippet of the proto file:

Pseudocode for invoking the Publish RPC might look something like this:

publishresponse = stub.Publish(stub.PublishRequest(topic_name = '/event/CustomOrder__e', events = makeProducerEvents())

Example: how to subscribe to Change Data Capture events in Python

The following walkthrough describes the overall steps for subscribing to Change Data Capture events with a Python implementation of the Pub/Sub API. Because the API is a closed pilot, this is not intended to be a tutorial; pilot customers will get an official pilot guide with code examples after the pilot launches. This example is merely to show how simple the subscription process with the Pub/Sub API can be.

1. Make sure the object you want to track is enabled for Change Data Capture events in Setup.
2. Get the topic name that you want to subscribe to. For Change Data Capture events, the topic name is /data/ChangeEvents for all CDC events and /data/<Object>ChangeEvent for specific objects (e.g. /data/OpportunityChangeEvent for the Opportunity object).
3. Create a generator function to make a FetchRequest stream.
   def fetchReqStream(topic):
while True:
semaphore.acquire()
yield pb2.FetchRequest(
topic_name = topic,
replay_preset = pb2.ReplayPreset.LATEST,
num_requested = 1,
linger_ms = 0)
4. Create a decoding function to decode the payloads of events you subscribe to:
   import avro.schema
import avro.iodef decode(schema, payload):
schema = avro.schema.Parse(schema)
buf = io.BytesIO(payload)
decoder = avro.io.BinaryDecoder(buf)
reader = avro.io.DatumReader(writer_schema=schema)
ret = reader.read(decoder)
return ret
5. Make the subscribe call and handle any events that you get back. Decode the payloads of the events with your decoding function.
   mysubtopic = <your subscription topic>
substream = stub.Subscribe(fetchReqStream(mysubtopic),
metadata=authmetadata)
for event in substream:
semaphore.release()
payloadbytes = event.events[0].event.payload
schemaid = eevent.events[0].event.schema_id
schema = stub.GetSchema(pb2.SchemaRequest(schema_id=schemaid),
metadata=authmetadata).schema_json
decoded = decode(schema, payloadbytes)
print("Got an event!", decoded)

Sign up for the pilot

The Pub/Sub API opens up a new world of possibilities for Salesforce developers. With an API that subscribes, publishes, retrieves schema, does flow control, and sends publish acknowledgements, it’s never been easier to build or improve on event-driven integrations. The real-time and highly performant nature of events sent with the Pub/Sub API makes it optimal for any integration fabric, and the decreased time spent on maintenance will make it the gift that keeps on giving.

Indicate your interest in trying out the Pub/Sub API to your Account Executive today! After they sign you up for the August pilot, you’ll receive pilot onboarding documentation and quickstart examples in different programming languages. We’re so excited to bring this new API to our customers, and we can’t wait to see what they build.

About the author

Emmett Chen-Ran is an Associate Product Manager on the Event Bus team (Platform). The APM program enables new grad product managers to work in three different Clouds for eight months each before joining a permanent team. Emmett’s previous rotation was on Sales Cloud, where he worked on Pipeline Inspection with the Pipeline Experience team.