Consuming Salesforce Platform Events with MuleSoft
Salesforce Platform Events let applications publish purpose-built business events to the Salesforce event bus. MuleSoft can subscribe to those events and route them into APIs, databases, queues, data platforms, and other enterprise systems.
The basic subscription is straightforward. Production reliability is not.
A robust consumer must decide what the event means, how replay is handled, when an event is considered safely accepted, how duplicate processing is prevented, and what happens when downstream systems are unavailable.
Treat the Salesforce subscription as an ingestion boundary, not automatically as the completion boundary for the business process.
Platform Events vs. Change Data Capture
The two Salesforce event mechanisms serve different purposes.
CDC
Salesforce record changed
│
▼
...ChangeEvent
Platform Event
Application publishes a business/system event
│
▼
...__e
CDC is useful when consumers need to react to record changes. Platform Events are useful when the producer wants to publish an intentional event contract such as OrderApproved, ProvisioningRequested, or CustomerOnboardingStarted.
For the CDC path, see Consuming Salesforce Change Data Capture Events with MuleSoft.
Subscribe from MuleSoft
MuleSoft's Salesforce Pub/Sub Connector provides a Subscribe Channel Listener for Salesforce Pub/Sub API topics. For a custom Platform Event such as:
Order_Approved__e
the event topic follows the Platform Event form:
/event/Order_Approved__e
A typical flow begins conceptually as:
Salesforce Event Bus
│
▼
MuleSoft Subscribe Channel Listener
│
▼
Validate / Normalize
│
▼
Business Processing
Authentication, secrets, and environment-specific values should be externalized rather than embedded in application configuration.
Understand Replay Before Choosing a Replay Option
Salesforce currently retains Platform Events and CDC events on the event bus for 72 hours. Each delivered event has an opaque Replay ID representing its position in the event stream.
Replay IDs should not be treated as contiguous sequence numbers or business identifiers.
The current MuleSoft Salesforce Pub/Sub Connector supports these subscription strategies:
- Latest — receive events published after the subscription begins.
- Earliest — receive retained events available in the server retention window, followed by new events.
- Custom Replay ID — resume after a supplied Replay ID.
- Replay ID from Object Store — resume using a Replay ID stored in Mule Object Store; if none is present, MuleSoft documents fallback to Earliest.
The Replay ID answers:
Where should this subscriber resume reading the Salesforce stream?
It does not by itself answer whether downstream business processing succeeded.
Decide What Your Checkpoint Means
A saved Replay ID can represent different processing boundaries:
last event received
last event durably handed off
last event fully processed
Those guarantees are different.
Consider this sequence:
receive event
save replay position
call downstream API
If Mule crashes after saving the replay position but before the API call succeeds, the subscriber can resume after work that never completed.
Reverse the order:
receive event
call downstream API successfully
Mule crashes before checkpoint
The event can be delivered again after restart. If the downstream operation is not idempotent, the business effect can happen twice.
Therefore:
Salesforce replay position
≠
business processing completion
≠
failed-event recovery state
Use a Durable Handoff When the Business Process Is Important
When downstream processing is slow, failure-prone, or business-critical, keep the Salesforce subscriber relatively thin:
Salesforce Platform Event
│
▼
MuleSoft Subscriber
│
├── validate
├── normalize
└── durable handoff
│
▼
Queue / Broker
│
▼
Business Processor
A useful checkpoint boundary then becomes:
receive event
│
▼
write work durably
│
▼
advance replay checkpoint
The internal processing tier can independently apply retries, backpressure, dead-letter handling, and recovery without keeping Salesforce ingestion blocked on a downstream outage.
This extra boundary is not mandatory for every flow. A small, low-risk integration can process directly. Use it when the reliability requirement justifies the additional component.
Normalize the Event Contract
Avoid propagating Salesforce-specific transport details throughout the enterprise.
A MuleSoft transformation layer can map the event into a stable internal representation:
{
"eventId": "APPROVAL-8472-V3",
"eventType": "OrderApproved",
"businessId": "ORD-8472",
"source": "salesforce",
"correlationId": "...",
"payload": {
"orderId": "ORD-8472",
"approvalStatus": "Approved"
}
}
The exact fields depend on the use case. Keep these concepts distinct:
- Salesforce stream/replay metadata
- logical event identity
- business entity identity
- correlation or trace identity
- business payload
Carry Data in the Event or Re-Fetch Salesforce?
A Platform Event can contain enough information to process the event independently, or it can carry an identifier that MuleSoft uses to query Salesforce.
Event-carried state
OrderApproved
├── OrderId
├── Status
├── Amount
└── ApprovedAt
This can preserve event-time state and avoid a synchronous Salesforce query during processing. The trade-offs are larger contracts, duplicated data, and data-governance considerations.
Reference-oriented event
OrderApproved
└── OrderId
│
▼
MuleSoft queries Salesforce
This keeps the event small and obtains current authoritative data, but processing now depends on Salesforce availability and may observe state newer than the state that existed when the event was published.
Hybrid
Often the event carries enough information to explain the business occurrence plus an identifier for additional lookup when needed.
The key is to decide whether the consumer needs event-time state or current state.
Replay ID Is Not Your Business Idempotency Key
A Replay ID identifies a position in the Salesforce stream. Duplicate business effects should normally be protected using a stable logical operation or event identifier.
For example:
business event ID = APPROVAL-ORD-8472-V3
Salesforce replay ID = opaque stream position
processing attempt = unique Mule execution
If the event causes MuleSoft to create a shipment and the target succeeds but the response is lost, replaying the event can create another shipment unless the target operation is protected.
Possible safeguards include:
- a stable idempotency key
- target uniqueness on a business identifier
- lookup/reconciliation after ambiguous timeouts
- a processed-event ledger
- state-convergent operations where appropriate
See Designing Idempotent Integrations in Distributed Systems for the broader pattern.
Classify Failures Before Retrying
Not every failure should be replayed immediately.
| Failure | Example | Typical direction |
|---|---|---|
| transient | short network interruption | bounded retry |
| throttling | target rate limit | delayed retry/backoff |
| extended outage | downstream unavailable | durable recovery |
| invalid event | required field missing | quarantine |
| business rejection | target rejects current state | remediation |
| ambiguous outcome | target may already have committed | reconcile first |
| stale work | newer state supersedes the event | domain-specific handling |
Blind retry can turn a dependency outage into additional load or duplicate a non-idempotent effect.
Use an Error Hospital for Remediation Workflows
A failed event that requires correction or investigation can leave the normal path:
Platform Event
│
▼
Normal Processing
│
├── success
│
└── recoverable failure
│
▼
Error Hospital
│
remediate / verify
│
▼
controlled replay
The recovery store does not always need the complete original event. Depending on the requirements, it can retain the event, a protected reference, a business identifier, or selected recovery metadata.
If recovery re-fetches Salesforce by business identifier, remember that the replay is now processing current Salesforce state, not necessarily reproducing the original historical event.
The 72-Hour Window Is Short-Term Recovery, Not an Archive
Salesforce documents a 72-hour retention window for Platform Events and CDC events. Availability beyond that window is not guaranteed.
That means Salesforce replay should be viewed as short-term stream recovery—not indefinite disaster recovery.
This is particularly important for Platform Events. A CDC gap can sometimes be repaired by querying current record state. A business Platform Event may represent a historical fact or command that cannot be reconstructed from the current Salesforce record.
For important events, consider whether you need:
- an independent durable copy after ingestion
- a downstream broker with longer retention
- a publisher-side business record that can regenerate the intent
- a reconciliation process
- operational escalation before the replay window expires
Prevent Event Ping-Pong
Bidirectional integrations can accidentally create loops:
Salesforce event
│
▼
MuleSoft updates System B
│
▼
System B integration updates Salesforce
│
▼
Salesforce publishes another event
└──────────────▶ loop
Useful controls include correlation/causation identifiers, source markers, no-op detection, and clear event ownership rules. The design should prevent technical loops without suppressing legitimate later business changes.
Backpressure Matters
A subscriber can receive events faster than a downstream API can safely process them.
Define controls for:
- processing concurrency
- queue depth
- downstream rate limits
- retry backoff
- circuit breaking
- replay throttling
- backlog alerting
The connector's batch size controls event retrieval efficiency. It is not a substitute for downstream capacity management.
Observability
Useful production signals include:
- last event received time
- current replay/checkpoint position
- ingestion rate
- durable-handoff latency
- processing backlog size and age
- duplicate events detected
- retry and retry-exhaustion rates
- recovery backlog
- replay success rate
- downstream latency and failure rate
Track at least three separate identities in logs and traces:
business identity
logical event identity
processing attempt identity
That makes duplicate deliveries and recovery attempts much easier to diagnose.
Practical Design Checklist
Before deploying a Platform Event consumer, confirm:
- The event represents a clear business contract.
- The consumer uses the intended Pub/Sub topic.
- The replay strategy matches startup and recovery requirements.
- The meaning of the saved checkpoint is explicit.
- Replay IDs are not treated as business identifiers.
- Duplicate business effects are protected by idempotency or reconciliation.
- Event-carried state versus Salesforce re-fetch is an intentional choice.
- Sensitive data is not copied into events or recovery stores unnecessarily.
- Important work has a durable handoff when downstream risk warrants it.
- Retry policy distinguishes transient from business failures.
- Ambiguous outcomes are reconciled before replay.
- Event loops are prevented in bidirectional integrations.
- Backpressure and replay traffic cannot overwhelm downstream systems.
- Recovery exists for failures requiring remediation.
- There is a plan for outages that exceed Salesforce's event-retention window.
- Ingestion, processing, checkpoint, and recovery health are observable.
Closing Perspective
Consuming a Salesforce Platform Event from MuleSoft is easy to demonstrate. Making that event safe through disconnects, duplicate delivery, downstream outages, replay, and recovery requires more deliberate architecture.
Use the Replay ID for what it is: a stream position. Give the business event its own stable identity. Decide exactly when a checkpoint can advance. Add a durable handoff when downstream processing needs independent reliability. Make side effects idempotent, and provide a recovery path for failures that cannot be solved by retry.
That turns a connector subscription into a dependable event-driven integration.