Salesforce Event-Driven Architecture
A reference design for publishing Salesforce changes as events, delivering them to external consumers, and handling ordering, replay, duplicates and failures.
An event-driven architecture lets Salesforce announce that something happened, such as an order was approved or a contact changed, and lets other systems react without Salesforce calling each of them directly. It reduces polling, isolates failures and makes it easier to add consumers later. It also brings its own problems: duplicates, ordering, replay windows and failed messages. This page is a reference design; we validate the APIs, edition and permissions for each implementation.
Business context
Point-to-point callouts from triggers are a common source of fragile orgs: a slow ERP blocks a save, and a new consumer means new Apex. Events break that coupling. Salesforce offers two main event types. Change Data Capture (CDC) publishes record changes for selected objects. Platform events carry business events you define, published from Flow, Apex or APIs. External clients subscribe through the Pub/Sub API (gRPC over HTTP/2, with Avro payloads), which Salesforce describes as a newer API than the Streaming API; the Streaming API is not marked deprecated. Inside the org, Apex triggers subscribe and run asynchronously after commit.
GeekMidst can design and implement event-driven integrations with MuleSoft or other middleware. See also platform events for decoupled integrations.
Salesforce event-driven reference architecture
Reference architecture: a reusable pattern, not a live client integration
Select a component to see what it is responsible for and how data moves to and from it.
Components and data flows (text version)
| Component | Type | Responsibility |
|---|---|---|
| Salesforce recordsselected objects | Salesforce product | Record changes on objects enabled for Change Data Capture. |
| Flow and Apexbusiness logic | Salesforce product | Publish platform events for business moments such as order approved, rather than calling external systems directly. |
| Data 360data actions | Data and analytics | Calculated insights can trigger data actions to platform events, Marketing Cloud or a webhook. |
| Change Data Capturechange events | Salesforce product | Publishes change events for selected objects. Change events are retained for 72 hours. |
| Platform eventscustom event types | Salesforce product | Carry your own event schema. High-volume platform events are retained for 72 hours; standard-volume events are no longer available. |
| Pub/Sub APIgRPC, HTTP/2, Avro | Integration layer | External clients subscribe, replay from a stored position and can use event filtering. |
| Apex trigger subscribersin-org | Salesforce product | Run asynchronously after commit. Event filtering is not available for Apex triggers. |
| Event relaymanaged relay | Integration layer | Relays events to an external event bus without custom subscriber code. Check supported targets in Salesforce documentation. |
| MiddlewareMuleSoft or other | Integration layer | Subscribes, transforms, deduplicates and routes events. Stores the last processed position and retries failures. |
| External event busyour cloud or streaming platform | External or custom system | Fans events out to many consumers and keeps its own retention for replay. |
| ERP and back officeconsumers | External or custom system | Process events idempotently, so the same event applied twice has no extra effect. |
| Data warehouseanalytics consumer | Data and analytics | Stores the event history for analysis and audit. |
| Dead-letter queuefailed messages | Identity, policy and governance | Holds messages that failed after the retry limit, with the error and payload, for review and replay. |
| Monitoringalerts and dashboards | People | Tracks consumer lag, error rates, dead-letter depth and event allocation usage. |
Data flows
- Salesforce records → Change Data Capture: record changes. Change events for enabled objects, published after the transaction commits.
- Flow and Apex → Platform events: publish. Flow or Apex publishes a platform event. If publishing fails, log it and alert; do not silently continue.
- Data 360 → Platform events: data actions. Insight-driven events, such as a lifetime value threshold crossed.
- Change Data Capture → Pub/Sub API: subscribe. External subscribers receive change events through Pub/Sub API.
- Platform events → Pub/Sub API: subscribe. External subscribers receive platform events, optionally filtered.
- Platform events → Apex trigger subscribers: in-org handling. Apex trigger subscribers run asynchronously after commit, for work that belongs inside Salesforce.
- Platform events → Event relay: relayed events. A managed relay to an external bus, as an alternative to running a subscriber.
- Pub/Sub API → Middleware: event stream. Middleware keeps the last processed position. After an outage shorter than the 72-hour retention window it can resume from that position; beyond it, run a reconciliation.
- Event relay → External event bus: relayed events. Events land on a supported external bus. Event relays support specific targets only, so confirm yours is one of them.
- Middleware → External event bus: normalised events. Middleware publishes cleaned, versioned events for many consumers.
- External event bus → ERP and back office: business events. Consumers deduplicate on an event identifier and check record versions before applying changes.
- External event bus → Data warehouse: event history. Stored for analytics and audit.
- Middleware → Dead-letter queue: failed after retries. Messages that keep failing go to the dead-letter queue with the error, so the stream keeps moving.
- Dead-letter queue → Monitoring: depth alerts. Alert when the queue grows or a message ages past an agreed limit.
- ERP and back office → Salesforce records: status write-back. Consumers that update Salesforce call its APIs through an integration user, not by publishing loops of events.
Component responsibilities
| Component | Responsible for | Key design decision |
|---|---|---|
| Change Data Capture | Announcing record changes | Which objects and fields to enable |
| Platform events | Announcing business events | Event schema and versioning |
| Pub/Sub API | Delivering events to external clients | Filters and stored replay position |
| Apex trigger subscribers | In-org reactions | Keep them small; no filtering available |
| Middleware | Transform, deduplicate, route, retry | Retry policy and dead-letter rules |
| External event bus | Fan-out and longer retention | Topics, partitions and retention |
| Consumers | Applying changes safely | Idempotency keys and version checks |
Data flow, step by step
- A user approves an order. A record-triggered flow publishes an
Order_Approvedplatform event; CDC also publishes the Order change. - Middleware, subscribed through Pub/Sub API, receives the event, validates the schema and checks whether it has already processed that event identifier.
- Middleware publishes a normalised event to the external bus and saves its new position.
- The ERP consumer applies the change. If the ERP rejects it, middleware retries with backoff and, after the limit, sends it to the dead-letter queue.
- The ERP writes the fulfilment status back to Salesforce through the REST API, using its own integration user.
Ordering, replay and idempotency
- Ordering: do not assume a global order across event types or objects. Carry a record version or timestamp, and have consumers ignore changes older than the one they hold.
- Replay: subscribers store their last position and resume from it. Salesforce retains high-volume platform and change events for 72 hours; PushTopic and generic events, now labelled legacy, for 24 hours. If an outage exceeds the window, run a reconciliation job instead of hoping for a replay.
- Idempotency: every consumer must tolerate duplicates. Use an event identifier or a business key with a version as the deduplication key.
- Dead-letter queue: a poison message must not block the stream. Park it with the error, fix the cause, then replay it deliberately.
Trust boundaries and authentication
External subscribers authenticate with OAuth through an External Client App, because Salesforce has said connected apps support ends in Summer '27. Give each subscriber a dedicated integration user with access only to the event channels and objects it needs. Credentials stay in the middleware's secrets store. Treat the external bus as a separate trust zone with its own access policies and encryption.
Failure scenarios and how to handle them
| Scenario | Effect | Handling |
|---|---|---|
| Subscriber down for hours | Events pile up | Resume from the stored position within 72 hours; reconcile beyond that |
| Duplicate delivery | Double processing | Idempotent consumers keyed on event identifier |
| Poison message | Stream stalls | Dead-letter after the retry limit, alert, fix and replay |
| Event allocation exhausted | Events not delivered | Monitor usage against your org's allocations; check limits in Salesforce documentation |
| Record-lock errors in flows | Failed saves | Winter '27 adds automatic retry on record-lock errors after 10 seconds (status not stated); design to avoid contention anyway |
| Schema change breaks consumers | Parsing failures | Version events and add fields without removing old ones |
Operational monitoring
Monitor consumer lag (time since the last processed event), error and retry rates, dead-letter depth and age, and event usage against allocations. Event Monitoring in Shield, a separate licence, adds API activity logs. Alert on silence too: a consumer that stops receiving events during business hours is often a failed subscription. Our integration error handling checklist lists the checks.
Alternative approaches and trade-offs
- Scheduled API polling. Simple, but adds load and latency, and misses intermediate states.
- Synchronous callouts from Flow or Apex. Fine when the user needs an immediate answer; risky for anything that can wait.
- Data virtualisation with Salesforce Connect. Shows external data without moving it; it does not notify anyone of changes. See API-led integration architecture.
Implementation checklist
- 01
List business events
Name each event, its producer, consumers and the decision it drives.
- 02
Choose CDC or platform events
CDC for record changes, platform events for business moments.
- 03
Design schemas
Include an event identifier, version and timestamp.
- 04
Build idempotent consumers
Deduplicate and check versions before applying changes.
- 05
Configure retries and a dead-letter queue
Agree retry limits, alerting and who reviews parked messages.
- 06
Test failure modes
Stop consumers, replay, send duplicates and exceed the window in a sandbox.
- 07
Set up monitoring
Dashboards and alerts for lag, errors, dead-letter depth and allocations.
Related services and solutions
API-led integration architecture
Layered APIs with MuleSoft
→Salesforce integration services
Design and build of integrations
→MuleSoft integration services
Anypoint Platform implementation
→Integration solutions
Patterns for connecting Salesforce
→Identity and consent architecture
Event-driven consent propagation
→API integration error handling
Retries, logging and alerts
→Questions we hear
Should we use CDC or platform events?
How long can a subscriber be offline?
Does Salesforce guarantee exactly-once delivery?
Do we need middleware?
Sources
- https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_subscribe.htm
- https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/using_streaming_api_durability.htm
- https://developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-dev-overview.html
- https://admin.salesforce.com/blog/2026/jens-top-winter-27-release-features-for-admins
- https://www.mulesoft.com/
Design integrations that survive failure
We can design your events, subscribers, retries and monitoring, and build them with MuleSoft or other middleware. Consultations are remote, from India.
