Subscribe RPC Method

The Subscribe method uses bidirectional streaming. It’s pull-based, which means that it requests new events. This subscription model is in contrast to push-based subscription, in which the subscriber is a listener that waits for events to be sent. The Subscribe method offers flow control, which enables you to specify how many events to receive in a call based on the client’s event processing speed.

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

A client can request the number of events it can process by setting the num_requested field in FetchRequest. The maximum value for num_requested is 100. The server returns the events in one or more FetchResponses. Each FetchResponse contains the number of events that are pending delivery in the pending_num_requested field. If a client requests more events before the server finishes the last requested amount, the server appends the new amount to the current batch of events it still needs to fetch and deliver. For more information about the pull subscription behavior, see Pull Subscription and Flow Control. For more information about the fields in FetchRequest and FetchResponse, see the Pub/Sub API proto file.

If there are pending requested events to deliver but no events are available in the event bus, the server sends an empty batch FetchResponse with the latest replay_id as a periodic keepalive message. The empty FetchResponse is sent within 270 seconds to indicate that the subscription is alive. The returned replay_id can be the last event consumed in your client or an advanced position in the stream beyond the last consumed event. An advanced position in the stream is possible even if you didn’t receive events because the event bus combines streams from multiple orgs. No org-specific information or personally identifiable information is shared with other orgs.

For best performance results, we recommend that you save the replay_id from each empty FetchResponse and use it when resubscribing. That way, you restart the subscription to get the next unprocessed event that is stored in the event bus, and you don’t fetch an old stream of events.

Platform events and change data capture events are retained in the event bus for 3 days. A client can subscribe at any position in the stream by providing a replay option in the first FetchRequest. Any subsequent FetchRequests with a new replay option are ignored. A client must call the Subscribe RPC again to restart the subscription at a new position in the stream. The replay option consists of a combination of replay_preset and replay_id values in the first FetchRequest received from a client.

This table describes the replay options and when to use each.

replay_preset	Behavior	When to Use
LATEST	Default if no replay preset is specified. Subscribe from the tip of the stream.	Use when you’re interested only in new event messages and don’t need the earlier event messages stored in the event bus.
CUSTOM	Resubscribe after a specific replay_id. To use this option, also set the replay_id to the replay ID of the last keepalive message or the last processed event message, whichever was received last. Store replay ID values as bytes because replay IDs are opaque and not guaranteed to always be numbers.	Use to catch up on missed events after a certain event message, for example, after a connection failure.
EARLIEST	Subscribe from the earliest retained events.	Use to catch up on missed events and retrieve all stored events. Use this option after a client has been disconnected for more than 3 days and the last saved replay ID is no longer valid. Use EARLIEST sparingly because it can slow performance when retrieving a large number of events.

The first FetchRequest of the stream identifies the topic to subscribe to. If a subsequent FetchRequest provides topic_name, it must match what was provided in the first FetchRequest. Otherwise, the RPC sends an error with an INVALID_ARGUMENT status.