Salesforce Pub/Sub API Flow Control: Request Only What You Can Process

A useful feature of Salesforce Pub/Sub API is easy to overlook: subscriptions are pull-based.

The subscriber tells Salesforce how many events it is prepared to receive by setting num_requested in a fetch request.

That is more than an API detail. It is a backpressure mechanism.

The Basic Model

A simplified subscription loop looks like this:

Consumer -> request N events
Salesforce -> deliver up to requested events
Consumer -> process events
Consumer -> request more capacity

The consumer controls how much additional work it asks the server to deliver.

Salesforce currently caps the requested event count at 100 for a Subscribe/ManagedSubscribe request sequence.

Why This Matters

Imagine your consumer can currently process only 20 more events safely because:

• its worker pool is nearly full,
• the downstream API is slow,
• database writes are taking longer,
• or an internal queue is approaching its high-water mark.

Requesting another large batch merely because the protocol allows it can create unnecessary pressure.

Instead, connect demand to actual processing capacity.

available worker capacity
        |
        v
requested event count

This is the same principle used in many resilient streaming systems: the consumer should participate in controlling flow.

Avoid the Infinite In-Memory Queue

A fragile design often behaves like this:

receive as fast as possible
        |
        v
put everything in memory
        |
        v
hope workers catch up

That works until a downstream dependency slows for several minutes.

Then memory becomes the buffer, and a runtime restart can turn backlog into lost work.

For critical processing, either keep intake aligned with capacity or durably hand off received work before acknowledging/checkpointing according to your chosen processing semantics.

Keep the Subscription Alive

Flow control also means the subscriber must manage the stream correctly.

When there are no pending requested events, Salesforce requires the client to send another fetch request within the documented stream interval to keep the subscription open. If the subscriber stops requesting, the stream eventually closes and must be re-established.

So "slow down" should normally mean request deliberately, not abandon subscription lifecycle management.

Combine Flow Control with Durable Processing

For higher-value integrations, a strong pattern is:

Pub/Sub API
    |
    v
controlled subscriber
    |
    v
durable queue / work store
    |
    v
bounded workers
    |
    v
downstream system

The subscriber controls intake. The durable layer protects accepted work. Workers protect downstream capacity.

Each layer has a clear responsibility.

Monitor the Difference Between Arrival and Processing

Flow control prevents uncontrolled ingestion, but it does not make slow processing disappear.

Monitor:

• event arrival rate,
• processing throughput,
• oldest outstanding work,
• queue depth,
• retry rate,
• and replay/checkpoint progress.

If Salesforce is producing events faster than you can sustainably process them, lag will grow somewhere. Detect that condition before the recovery window becomes a problem.

Final Rule

Do not treat num_requested as "always request the maximum."

Treat it as:

How much additional work can this consumer safely accept right now?

That turns Pub/Sub API flow control into part of the integration's reliability architecture rather than merely a subscription parameter.