Salesforce Platform Events Explained: How They Work and When to Use Them
Platform Events let Salesforce and your other systems tell each other what just happened, without point-to-point calls or constant polling. This guide covers how the event bus works, how to publish and subscribe with Flow, Apex and APIs, the limits that shape a design, and the standard-volume retirement on December 15, 2026.
Key Takeaways
- A platform event is a message with a schema you define. Publishers put it on the Salesforce event bus, and any number of subscribers, inside or outside Salesforce, react to it without knowing about each other.
- Flow, Apex and the SOAP, REST, Bulk and Pub/Sub APIs can publish. Apex triggers, flows, Lightning components, Pub/Sub API and CometD clients can subscribe.
- Event messages are kept for 72 hours and can be replayed by API subscribers, but delivery is at-least-once, so subscribers must tolerate duplicates.
- Choose Change Data Capture when you only need to broadcast record changes, and Platform Events when you need a custom business message. PushTopic and generic events are legacy.
- Standard-volume platform events (defined in API version 44.0 or earlier) retire on December 15, 2026. Migrate them to high volume before that date.
What are Salesforce Platform Events? Salesforce Platform Events are secure, scalable messages that carry data you define. A publisher, such as a flow, an Apex class or an external system, sends an event message to the Salesforce event bus. Every subscriber to that event receives it in near real time and acts on it. Publishers and subscribers are decoupled, so you can add a new consumer without changing the system that publishes.
We first published this article in 2019. This version is rebuilt from Salesforce's current Platform Events Developer Guide, the Winter '27 release notes and the Salesforce Architects decision guide for event-driven architecture. It replaces the old references to Process Builder and the Cloud Flow Designer with today's Flow options. It also adds publish behavior, replay, limits, error handling, testing, the comparison with Change Data Capture and Pub/Sub API, and the standard-volume retirement. It is written for architects, admins and developers at growing and mid-market companies who connect Salesforce to ERP, billing, fulfilment or data platforms.
What Are Salesforce Platform Events, in Plain Terms?
They are Salesforce's built-in publish-and-subscribe messaging service. One system announces that something happened, such as "order shipped" or "payment failed". Every system that cares about it hears it and responds in its own way. The sender does not wait for an answer and does not need to know who is listening. Salesforce calls this its enterprise messaging platform, and it underpins event-driven integration across the platform.
Event producers
Flows, Apex code and external apps publish event messages. They do not know which consumers exist; the only contract is the event's fields.
The event bus
A multitenant, time-ordered event log that stores messages in the order received and delivers them to every subscriber.
Event consumers
Apex triggers, flows, Lightning components and external clients subscribe to the event's channel and react independently.
Source: Salesforce's event-driven software architecture overview in the Platform Events Developer Guide. Platform Events are available in Enterprise, Performance, Unlimited and Developer Editions, and are not supported in Professional or Group Edition orgs.
How Does the Salesforce Event Bus Deliver a Platform Event?
A publisher sends an event message, the bus queues and stores it, and each subscriber receives it asynchronously. High-volume event messages, the only kind you can create today, stay on the bus for 72 hours. Each message gets a ReplayId for position and an EventUuid for identity, so API subscribers can reconnect and pick up where they left off within that window.
__e plus custom fields. An event message is an instance of it, much as a record is an instance of an object.OPERATION_ENQUEUED: the request is queued, and the event is published asynchronously.Publish Immediately or Publish After Commit?
Each event definition has a publish behavior. It decides what happens when the Salesforce transaction that published the event fails.
| Setting | When the event goes out | Use it when | Watch out for |
|---|---|---|---|
| Publish Immediately (default) | As soon as the publish call runs, whether or not the transaction later succeeds | The event must go out even if the work fails, such as logging an error or a failed payment attempt | A subscriber can receive the event before the related data is committed; published events cannot be rolled back. In Apex it has its own limit of 150 EventBus.publish() calls per transaction |
| Publish After Commit | Only after the transaction commits successfully; never if it fails | Subscribers will read the record the transaction saved, such as an external system fetching a new order | Each publish call counts as a DML statement; setSavepoint() and rollback() work |
Sources: Define a custom platform event and platform events and the event bus. Publish behavior does not apply to events published through Pub/Sub API, and a change to the setting can take up to five minutes to apply.
Platform Events vs Change Data Capture vs PushTopic: Which Should You Use?
Use Change Data Capture to broadcast record changes, Platform Events to send a custom business message, and Pub/Sub API to connect external systems to either. Salesforce now describes PushTopic and generic events as legacy products that get no new features and limited support. It recommends Change Data Capture in place of PushTopic, and Platform Events in place of generic events.
| Mechanism | What triggers it | Payload | Retention | Status |
|---|---|---|---|---|
| Platform Events | You publish it from Flow, Apex or an API | Your own schema, up to 1 MB | 72 hours | Recommended |
| Change Data Capture | Salesforce publishes automatically on create, update, delete and undelete of selected objects | Changed fields plus a header; enrichment can add up to 10 unchanged fields such as an external ID | 3 days | Recommended |
| PushTopic events | Record changes matching a SOQL query | Fields in the query | 1 day | Legacy |
| Generic events | You publish an arbitrary payload | No definable schema | 1 day | Legacy |
| Outbound Messages | A flow or workflow rule sends an XML message to an external endpoint when field values change | Selected record fields | 24 hours | No further investment planned |
Sources: Salesforce's streaming event comparison, Change Data Capture Developer Guide and the Architects' event-driven architecture decision guide. Change Data Capture lets you select up to five entities by default, with an add-on to remove that limit.
For transport, Salesforce recommends Pub/Sub API instead of the older CometD-based Streaming API for new apps. Pub/Sub API uses gRPC, HTTP/2 and binary Apache Avro, lets the client control the flow of events, and returns the final publish result rather than only the queueing result. If your landscape already includes MuleSoft or another enterprise service bus, the Architects guide advises using it where possible. Our Streaming API guide covers the older PushTopic approach for teams maintaining existing builds.
When Should You Use Platform Events, and When Should You Not?
Use them when several systems need to react to the same business moment, and the publisher should not wait for them. Typical examples: an opportunity closes and fulfilment, billing and an ERP all need to know; an external system reports a return, a shipment or a device alert to Salesforce; a long Apex process hands work off to run in its own transaction.
Order and fulfilment
A closed-won deal publishes an event that shipping, provisioning and ERP systems each consume on their own schedule.
Inbound signals
An external app publishes returns, payment results or IoT alerts into Salesforce, where a flow or trigger opens a case or updates a record.
Error and audit signals
Publish Immediately events record a failure even when the transaction rolls back. Salesforce's standard BatchApexErrorEvent reports batch Apex errors the same way.
Live screens
A Lightning component subscribes with lightning/empApi to refresh a console or dashboard without a page reload, for a limited number of internal users.
Decoupled processing
Heavy work moves to a subscriber that runs asynchronously with fresh governor limits, keeping the user's save fast.
Cloud integration
Event Relays send platform events and change events to Amazon EventBridge with low-code setup, and can bring events back from AWS.
Good fit. More than one consumer needs the same signal. The publisher should not slow down or fail because a consumer is busy. You can describe the message as a stable business fact ("Invoice Paid") with a small set of fields. Consumers can tolerate a short delay and the occasional duplicate.
Poor fit. A person is waiting on screen for the other system's answer: use a synchronous callout instead. The data changes so rarely that a scheduled batch is enough. You only need to copy record changes to another store: Change Data Capture does that without code. You need an audit trail: Salesforce does not recommend Change Data Capture for that either.
The good and poor fits follow the Architects decision guide and Trailhead's Platform Events Basics module. The guide also names a real trade-off: once publishers and subscribers agree on a message structure, changing it is hard, so design the fields carefully up front.
How Do You Create a Platform Event in Salesforce?
In Setup, enter Platform Events in Quick Find, click New Platform Event, give it a label and object name, choose the publish behavior, and add custom fields. You need the Customize Application permission. Salesforce appends __e to the API name, so an object name of Order_Shipped becomes Order_Shipped__e. Every event you create this way is high volume.

- Field types. Checkbox, Date, Date/Time, Number, Text and Text Area (Long). There are no lookups or picklists, so carry IDs or external IDs as text.
- Field security. All event fields are read-only and field-level security does not apply: every subscriber receives every field. Leave sensitive data out, or encrypt messages at rest with Shield Platform Encryption.
- Where to find it. Platform events do not appear in Object Manager or Schema Builder, have no tab or page layout, and cannot be queried with SOQL.
- Permissions. Publishing needs Create on the event; subscribing needs Read. Grant them with a permission set.
- Deployment. Definitions deploy with Metadata API like any other metadata. Deleting a definition is permanent.
Source: Define a custom platform event and considerations for defining and publishing platform events.
How Do You Publish Platform Events from Flow, Apex and External Systems?
Flow publishes with a Create Records element on the event, Apex calls EventBus.publish(), and external systems insert the event through the REST, SOAP, Bulk 2.0 or Pub/Sub API. Older processes built in Process Builder can publish too. Whichever you use, a successful result means the event was queued, not yet delivered.
| Publisher | How | Good to know |
|---|---|---|
| Flow | Create Records element, with the platform event as the object | No code; the easiest way for admins to emit a business event from a record-triggered flow |
| Apex | EventBus.publish(event) or a list of events | Partial success, like Database.insert: check each SaveResult. Add publish callbacks to get the final result. From API version 67.0 it runs in user mode |
| REST, SOAP, Bulk API 2.0 | Insert the event like an sObject; REST composite for several at once | Consumes daily API request allocation; allOrNone applies only to Publish After Commit events |
| Pub/Sub API | gRPC publish, or a bidirectional publish stream | Returns the final publish result; does not consume API request allocation |
A minimal Apex publish, checking each result:
List<Order_Shipped__e> events = new List<Order_Shipped__e>{
new Order_Shipped__e(Order_Number__c = 'SO-10425', Carrier__c = 'UPS')
};
List<Database.SaveResult> results = EventBus.publish(events);
for (Database.SaveResult sr : results) {
if (!sr.isSuccess()) {
for (Database.Error err : sr.getErrors()) {
System.debug(err.getStatusCode() + ': ' + err.getMessage());
}
}
}Two Apex details trip teams up. EventBus.publish() does not throw when an event fails, so code that ignores the SaveResult loses failures silently. And a trigger that publishes the same event it subscribes to can loop forever. Sources: publish with Apex, publish with Flow, publish with Salesforce APIs and the EventBus class reference.
How Do You Subscribe to Platform Events?
Inside Salesforce, use a platform event-triggered flow or an after insert Apex trigger. Outside Salesforce, use a Pub/Sub API client, a CometD client or an Event Relay. Pick by who maintains it and what it must do: flows for admin-owned logic, triggers for high volume and fine control, and Pub/Sub API for external systems that need replay.
| Subscriber | Batch and context | Best for |
|---|---|---|
| Apex trigger (after insert only) | Up to 2,000 events per batch; runs as the Automated Process user by default | High volume, retries and checkpoints, complex logic |
| Platform event-triggered flow | Up to 200 events per batch; runs in the context of the user who published the event | Admin-maintained reactions such as creating a task or updating a record |
Lightning component (lightning/empApi) | Each logged-in user counts as one concurrent CometD client | Live UI for internal users; not recommended for apps with many users, such as Experience Cloud sites |
| Pub/Sub API client | gRPC with client flow control and replay; managed subscriptions (Beta) store the last Replay ID on the server | Middleware, data platforms and services outside Salesforce |
| CometD client | Streaming API with replay | Existing integrations; new builds should use Pub/Sub API |
| Event Relay | Configured relay to Amazon EventBridge | AWS-based architectures, without middleware code |
A basic Apex trigger subscriber
Our original example subscribed to a "Cloud News" event and opened a high-priority case for urgent news. The pattern is still valid:

Cloud_News__e event that creates one case per urgent event and inserts them in bulk.Production subscribers need two more things. First, decide who the trigger runs as. By default, records it creates are owned by the Automated Process user, and some actions such as sending email with Messaging.SingleEmailMessage are not supported in that context. A PlatformEventSubscriberConfig record sets a named running user and a batch size from 1 to 2,000. Since Winter '27 you can edit it in Event Studio as well as through the Metadata or Tooling API. Second, plan for failures with a bounded retry:
trigger OrderShippedTrigger on Order_Shipped__e (after insert) {
List<Task> tasks = new List<Task>();
for (Order_Shipped__e evt : Trigger.new) {
tasks.add(new Task(Subject = 'Confirm delivery of ' + evt.Order_Number__c));
}
try {
insert tasks;
} catch (DmlException e) {
// resend the whole batch later, at most 4 times
if (EventBus.TriggerContext.currentContext().retries < 4) {
throw new EventBus.RetryableException(e.getMessage());
}
// after that, log the failure (for example to a custom log object)
}
}Keep one trigger per event object, because Salesforce does not guarantee the order in which several triggers on the same event run. For very high volumes, parallel subscriptions split a trigger's work across up to 10 partitions, at the cost of ordering across partitions. Sources: subscribe with Apex triggers, configure the trigger's user and batch size, subscribe with flows, subscribe in a Lightning component and Event Relays. For background on asynchronous processing, see our guide to asynchronous Apex.
What Are the Platform Event Limits and Allocations?
Two allocations shape most designs: an hourly publishing allocation and a 24-hour delivery allocation for API subscribers. Deliveries to Apex triggers and flows do not count against delivery. Deliveries to Pub/Sub API, CometD, empApi and Event Relay clients do, once per client, so two external subscribers double the count.
| Allocation | Performance and Unlimited | Enterprise | Developer |
|---|---|---|---|
| Events published per hour (all methods) | 250,000 | 250,000 | 50,000 |
| Events delivered to API clients (rolling 24 hours, shared with Change Data Capture) | 50,000 | 25,000 | 10,000 |
| Platform event definitions | 100 | 50 | 5 |
| Concurrent CometD clients | 2,000 | 1,000 | 20 |
| Maximum event message size | 1 MB | 1 MB | 1 MB |
Sources: default publishing and delivery allocations and common platform event allocations. An add-on licence adds 100,000 delivered events per day and 25,000 publishes per hour, on a monthly usage-based entitlement. Publishing through REST, SOAP or Bulk API also uses your daily API request allocation; Pub/Sub API, Apex and Flow do not.
When you go over, the failure is abrupt. Publishing over the hourly allocation returns LIMIT_EXCEEDED and the events are not queued. Going over the delivery allocation disconnects subscribers until usage falls. Stream filters on a custom channel count deliveries after filtering, so filtering is the cheapest way to cut delivery usage. Track consumption with the PlatformEventUsageMetric object; enhanced usage metrics add hourly and 15-minute breakdowns by event and client.
How Do You Handle Errors, Test and Monitor Platform Events?
Design subscribers to be idempotent, bound their retries, test delivery explicitly, and watch both usage and trigger state. Salesforce publishes asynchronously with at-least-once delivery. Rare duplicates carry the same EventUuid, and in rare cases an event is not persisted at all. Reliable designs plan for both.
EventBus.RetryableException resends the whole batch after an increasing delay and rolls back DML from that run. A trigger runs at most 10 times (the first run plus 9 retries) and then enters an error state, stops receiving events, and emails a notification. Salesforce recommends fewer than 9 retries.setResumeCheckpoint(replayId) marks the last event processed, so if the trigger stops early, the next run resumes after it instead of reprocessing the batch.Test.stopTest() runs, or on demand with Test.getEventBus().deliver(). Use Test.getEventBus().fail() to test failed publishes.@IsTest
private class OrderShippedTriggerTest {
@IsTest static void createsFollowUpTask() {
Test.startTest();
EventBus.publish(new Order_Shipped__e(Order_Number__c = 'SO-1'));
Test.stopTest(); // delivers the event to the trigger
System.assertEquals(1, [SELECT COUNT() FROM Task]);
}
}Sources: retry event triggers with RetryableException, resume a trigger from a checkpoint, test platform event triggers, event message durability and the Winter '27 platform events release notes. The same thinking applies to fault paths in flows: see our guide to Salesforce Flow fault path strategies.
What Happens to Standard-Volume Platform Events on December 15, 2026?
They retire: after December 15, 2026, nobody can publish or subscribe to them. Standard-volume events are those defined in API version 44.0 or earlier, before high volume became the default in API version 45.0. If your org defined events before the Spring '19 release, check them now.
How to migrate. In Winter '27, a button on Setup > Platform Events converts all standard-volume events in one step. Since Summer '26, the PlatformEventMigration Metadata API type converts them one at a time, which suits teams that deploy through a pipeline.
Plan a window. Salesforce says the button migration should take about 15 minutes but can take up to 24 hours. Publishing does not work, and new triggers and flows cannot be created, while it runs. High-volume events also behave differently: 72-hour retention, asynchronous publishing and different allocations, so retest subscribers.
Source: Salesforce Help, Standard-Volume Platform Events retirement (updated October 2026). Some Developer Guide pages still say Summer '27; the Help article and Winter '27 release notes give December 15, 2026, so plan for the earlier date.
What Are the Most Common Platform Event Mistakes?
Most problems come from treating events like synchronous calls: assuming exactly one delivery, instant processing, or a guaranteed order across calls. Check for each of these before any event-driven Salesforce build goes live.
EventBus.publish() does not throw on failure. Unchecked results hide lost events.The Bottom Line
Salesforce Platform Events turn integrations from a web of point-to-point calls into one published fact that every system can act on. They are reliable when designed for how they really behave: asynchronous, at-least-once, replayable for 72 hours, and bounded by allocations. Twopir Consulting designs and builds Salesforce integrations across Apex, Flow, MuleSoft and other middleware. Our real-time leaderboard case study shows an earlier streaming build for a sales team.
- 1
Choose the mechanism: Change Data Capture for record changes, Platform Events for business messages, Pub/Sub API for external clients.
- 2
Design the event's fields as a stable contract, and choose Publish Immediately or Publish After Commit on purpose.
- 3
Make subscribers idempotent, set a running user, and cap retries below the limit.
- 4
Size publishing and delivery allocations for every external subscriber, and monitor usage.
- 5
Migrate any standard-volume events before December 15, 2026.
Build Event-Driven Salesforce Integrations That Hold Up
Tell us which systems need to react to what. We will map the events, subscribers and allocations, and check your org for standard-volume events before the retirement date.
Schedule a Discovery CallFrequently Asked Questions
A platform event is a message with a schema you define, like a custom object whose API name ends in __e. Flows, Apex or external systems publish event messages to the Salesforce event bus, and every subscriber, such as an Apex trigger, a flow or an external Pub/Sub API client, receives them in near real time and reacts independently.
Change Data Capture publishes events automatically when selected records are created, updated, deleted or undeleted, so it suits copying record changes to other systems. Platform Events carry a custom business message that you publish yourself from Flow, Apex or an API. Both use the same event bus, 72-hour retention and delivery allocation.
High-volume platform event messages are stored on the event bus for 72 hours. Pub/Sub API and CometD subscribers can replay them within that window by resubscribing with a stored ReplayId. Apex triggers and flows cannot replay past events. Legacy standard-volume events were kept for 24 hours.
Yes. A flow publishes an event with a Create Records element on the platform event. A platform event-triggered flow subscribes to it, receives up to 200 events per batch, and runs asynchronously in the context of the user who published the event. A Pause element can also resume a waiting flow when a matching event arrives.
By default, Performance, Unlimited and Enterprise orgs can publish 250,000 events per hour. Delivery to API subscribers is limited to 50,000 events in 24 hours on Performance and Unlimited and 25,000 on Enterprise, counted per client. Deliveries to Apex triggers and flows do not count. An add-on raises both allocations.
No. Salesforce publishes events asynchronously with at-least-once delivery, so rare duplicates can arrive with the same EventUuid, and in rare cases an event is not persisted at all. Make subscribers idempotent, check publish results or use publish callbacks, and use replay for API subscribers that reconnect.
Standard-volume platform events, those defined in API version 44.0 or earlier, retire on December 15, 2026, after which they cannot be published or subscribed to. Migrate them to high volume with the Winter '27 button in Setup or the PlatformEventMigration Metadata API type, and retest subscribers afterwards.
Platform Events are available in Enterprise, Performance, Unlimited and Developer Editions, in both Lightning Experience and Salesforce Classic. They are not supported in Professional or Group Edition orgs, and installing a package that contains platform event objects fails there.
Twopir Consulting
Twopir Consulting helps growing and mid-market companies solve complex CRM, integration, and business system challenges. We implement, rescue, optimize, and integrate complex CRM and revenue systems, including event-driven Salesforce integrations with Apex, Flow and MuleSoft, for 500+ clients over 12+ years.