Receive events in an external system with Pub/Sub API
Receive Record Health Check Platform Events in a system outside Salesforce, such as middleware, a data warehouse, or a monitoring service, with Salesforce Pub/Sub API. For example, an integration receives one Record Health Check Set Run event per Account, saves it in a data warehouse, and feeds a long-term data-quality trend report.
Pub/Sub API uses gRPC over HTTP/2 and sends event data in Apache Avro format. Start from one of Salesforce’s sample clients rather than implementing the protocol yourself. When the work can stay inside Salesforce, a Platform Event-triggered Flow or Apex trigger is simpler; see Save or send results after a run.
Confirm in Salesforce’s Pub/Sub API documentation that Pub/Sub API is available for your org’s edition, and review its allocations, before you depend on it in production.
Choose the topic
Section titled “Choose the topic”Pub/Sub API platform-event topics use /event/<qualified-event-api-name>.
Topic after installing the rhc package | What it carries |
|---|---|
/event/rhc_ | Run summaries |
/event/rhc_ | Per-Check outcomes |
/event/rhc_ | Restricted diagnostics |
The event fields also carry the prefix in the Avro schema, such as rhc__EventId__c and
rhc__RunId__c. See the Platform Event field reference.
Prepare access
Section titled “Prepare access”- Create a dedicated Salesforce integration user and an approved OAuth configuration.
- Create a permission set your organization owns that grants API Enabled and Read access to only the events the integration needs. The Record Health Check permission sets are meant for users who run Checks, and Record Health Check MCP Integration grants no event access. Grant access to the Log event only after a security review.
- Store credentials in the integration platform’s secret manager. Never place access tokens, refresh tokens, client secrets, or Salesforce auth URLs in source control or logs.
- Confirm the org’s event delivery allocation and define alerts before enabling publication.
Create the External Client App or supported Connected App through the organization’s Salesforce identity standard. Use a dedicated integration user, an approved OAuth flow, API access, and Read access only to the required event objects. This page does not prescribe a universal client-secret or certificate policy; follow the security owner’s rotation and revocation requirements.
The external system’s destination permissions are independent of Salesforce event access. Apply the destination’s own encryption, retention, deletion, and record-ID handling requirements.
Limits and transaction boundary
Section titled “Limits and transaction boundary”The external integration runs outside the Salesforce transaction that published the event. Its success or failure cannot change the completed health-check result. Size fetch requests for the integration’s real capacity, up to Salesforce’s maximum of 100 requested events per FetchRequest, and monitor the org’s event publishing and delivery limits. For high-volume processing, write receipts and destination records in bounded groups while preserving each event’s failure details.
Implement the subscription
Section titled “Implement the subscription”- Authenticate the dedicated integration user and supply the access token, instance URL, and tenant ID headers required by the client.
- Call
GetTopicandGetSchema, then decode event data with the returned Avro schema. Ignore additive fields that the current contract version does not use. - Start the first subscription with
LATESTwhen only new events are wanted, orEARLIESTfor a deliberate backfill of events still retained on the bus. - Set
num_requestedto the number of events the integration can process, up to 100. Send another FetchRequest as capacity becomes available. This is Pub/Sub API flow control. - Validate the contract version and required fields. Store a durable receipt keyed by
rhc__EventId__c, then perform the destination action. - After durable processing, save the Replay ID from the last processed event. If a later empty keepalive response arrives, save its Replay ID instead because it represents the later received stream position. Store the bytes exactly as received; do not compare them numerically.
- On a temporary stream failure, reconnect with
CUSTOMand the saved Replay ID. Use exponential backoff with jitter and alert on sustained disconnection or processing lag.
Keep three identifiers separate
Section titled “Keep three identifiers separate”| Identifier | Do not use it for | Purpose |
|---|---|---|
rhc_ | Stream position | Record Health Check application-level deduplication |
| Pub/Sub event ID | Business correlation or stream position | Unique identity assigned to the Salesforce event message |
| Replay ID | Deduplication, ordering arithmetic, or business identity | Opaque position used to resume a retained stream |
Replay IDs are not guaranteed to be contiguous. Store them as opaque bytes exactly as received; never increment, compare numerically, or
manufacture one. Record Health Check’s rhc__RunId__c connects related events but is not a unique
receipt key.
Recover safely
Section titled “Recover safely”Salesforce stores high-volume Platform Events for 72 hours. Events can remain available longer, but Salesforce does not guarantee storage beyond 72 hours. If a saved Replay ID is invalid or outside that window, choose a documented recovery policy:
- Use
LATESTwhen losing missed notifications is acceptable. - Use
EARLIESTto process everything still retained, accepting duplicates and load. - Reconcile from the integration’s durable receipts or Salesforce source records when completeness is required. Do not claim that the event stream can reconstruct data older than its retention window.
Handle permission errors, exhausted delivery allocations, malformed requests, and invalid replay IDs separately from temporary service failures. A permanent event-data error belongs in a review or dead-letter store; repeatedly reconnecting does not repair it.
Salesforce also offers ManagedSubscribe, which stores committed Replay ID progress on the server.
Check its current release status in Salesforce’s documentation before you depend on it.
Verify before production
Section titled “Verify before production”- Subscribe in a sandbox and publish a deliberate run with a known Run ID.
- Confirm field decoding, durable receipt creation, and destination behavior.
- Deliver or replay the same event and confirm that
rhc__EventId__cprevents a duplicate side effect. - Disconnect the client, publish events, reconnect with
CUSTOM, and confirm catch-up. - Test an invalid contract version, a destination outage, an expired or invalid replay ID, and a restricted Log event.
- Monitor connection state, last receipt time, processing lag, retry count, dead-letter count, event allocation usage, and age of the saved checkpoint.
Official Salesforce references
Section titled “Official Salesforce references”- Pub/Sub API overview
- Subscribe RPC and flow control
- Event message durability and replay
- Retry long-lived RPC calls
- Pub/Sub API errors
- Managed subscriptions