Salesforce · Integration · Event-Driven Architecture

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.

Section 01 · Short Answer

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.

Section 02 · How It Works

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.

1. You define the event.
→ Like a custom object: a name ending in __e plus custom fields. An event message is an instance of it, much as a record is an instance of an object.
2. A publisher sends it.
→ A successful publish returns OPERATION_ENQUEUED: the request is queued, and the event is published asynchronously.
3. The bus stores it in order.
→ Messages are stored in the order Salesforce receives them. Order is guaranteed within one publish call, not across separate calls.
4. Subscribers receive it.
→ Apex triggers and flows run in their own asynchronous transaction. API clients receive it over Pub/Sub API or CometD. Nobody sends an acknowledgement back to the publisher.
5. API clients can replay.
→ A Pub/Sub API or CometD client that stores the last ReplayId it processed can resubscribe and receive the events it missed, within 72 hours. Apex triggers and flows cannot replay past events.

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.

SettingWhen the event goes outUse it whenWatch out for
Publish Immediately (default)As soon as the publish call runs, whether or not the transaction later succeedsThe event must go out even if the work fails, such as logging an error or a failed payment attemptA 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 CommitOnly after the transaction commits successfully; never if it failsSubscribers will read the record the transaction saved, such as an external system fetching a new orderEach 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.

Section 03 · Options

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.

MechanismWhat triggers itPayloadRetentionStatus
Platform EventsYou publish it from Flow, Apex or an APIYour own schema, up to 1 MB72 hoursRecommended
Change Data CaptureSalesforce publishes automatically on create, update, delete and undelete of selected objectsChanged fields plus a header; enrichment can add up to 10 unchanged fields such as an external ID3 daysRecommended
PushTopic eventsRecord changes matching a SOQL queryFields in the query1 dayLegacy
Generic eventsYou publish an arbitrary payloadNo definable schema1 dayLegacy
Outbound MessagesA flow or workflow rule sends an XML message to an external endpoint when field values changeSelected record fields24 hoursNo 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.

Section 04 · Use Cases

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.

Section 05 · Define

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.

Salesforce Setup, Platform Events page, editing a platform event definition named Cloud News with Label, Plural Label and Object Name fields
The platform event definition screen in Setup, from our original example event "Cloud News". Today's screen also includes the Publish Behavior setting.
  • 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.

Section 06 · Publish

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.

PublisherHowGood to know
FlowCreate Records element, with the platform event as the objectNo code; the easiest way for admins to emit a business event from a record-triggered flow
ApexEventBus.publish(event) or a list of eventsPartial 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.0Insert the event like an sObject; REST composite for several at onceConsumes daily API request allocation; allOrNone applies only to Publish After Commit events
Pub/Sub APIgRPC publish, or a bidirectional publish streamReturns 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.

Section 07 · Subscribe

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.

SubscriberBatch and contextBest for
Apex trigger (after insert only)Up to 2,000 events per batch; runs as the Automated Process user by defaultHigh volume, retries and checkpoints, complex logic
Platform event-triggered flowUp to 200 events per batch; runs in the context of the user who published the eventAdmin-maintained reactions such as creating a task or updating a record
Lightning component (lightning/empApi)Each logged-in user counts as one concurrent CometD clientLive UI for internal users; not recommended for apps with many users, such as Experience Cloud sites
Pub/Sub API clientgRPC with client flow control and replay; managed subscriptions (Beta) store the last Replay ID on the serverMiddleware, data platforms and services outside Salesforce
CometD clientStreaming API with replayExisting integrations; new builds should use Pub/Sub API
Event RelayConfigured relay to Amazon EventBridgeAWS-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:

Apex code for an after insert trigger on the Cloud_News__e platform event that creates a high-priority case, assigned to the Regional Dispatch queue, for each event marked urgent
An after insert trigger on the 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.

Section 08 · Limits

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.

AllocationPerformance and UnlimitedEnterpriseDeveloper
Events published per hour (all methods)250,000250,00050,000
Events delivered to API clients (rolling 24 hours, shared with Change Data Capture)50,00025,00010,000
Platform event definitions100505
Concurrent CometD clients2,0001,00020
Maximum event message size1 MB1 MB1 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.

Section 09 · Reliability

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.

Deduplicate.
→ Store the EventUuid (API version 52.0 and later) of processed events, or make the action safe to repeat, such as an upsert on an external ID. ReplayId is a position, not an identity.
Retry within limits.
→ 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.
Checkpoint large batches.
→ setResumeCheckpoint(replayId) marks the last event processed, so if the trigger stops early, the next run resumes after it instead of reprocessing the batch.
Know the Winter '27 change.
→ The Winter '27 release notes describe an update that rolls back a platform event trigger's transaction when it throws an unhandled exception, so partially written records are no longer committed. Do not design subscribers that rely on partial commits.
Test delivery.
→ In Apex tests, events publish when Test.stopTest() runs, or on demand with Test.getEventBus().deliver(). Use Test.getEventBus().fail() to test failed publishes.
Monitor.
→ Watch publishing and delivery usage, trigger status in Setup and Event Studio, and Event Monitoring log files for uncaught trigger exceptions. A sandbox refresh or org migration can reset the stored stream, so old Replay IDs stop working.
@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.

Section 10 · Retirement

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.

Section 11 · Pitfalls

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.

No duplicate handling. Delivery is at-least-once. Without an EventUuid check or an idempotent action, a rare duplicate creates a duplicate order or invoice.
The wrong publish behavior. Publish Immediately on an event whose subscriber reads the saved record means the subscriber can look before the data is committed.
Ignoring the SaveResult. EventBus.publish() does not throw on failure. Unchecked results hide lost events.
Unbounded retries. Retrying on every error pushes the trigger to its 10-run limit and into an error state, after which new events are not resent.
Automated Process surprises. Records owned by Automated Process, and email that cannot be sent. Set a running user with PlatformEventSubscriberConfig.
empApi on a busy portal. Every logged-in user is a concurrent CometD client. Experience Cloud sites with many users exhaust the limit.
Delivery allocation forgotten. Each external subscriber multiplies delivery usage. Filter channels and size the add-on before go-live.
Sensitive fields in the payload. Field-level security does not apply to event fields. Send IDs and let subscribers fetch what they are allowed to see.
Section 12 · Bottom Line

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. 1

    Choose the mechanism: Change Data Capture for record changes, Platform Events for business messages, Pub/Sub API for external clients.

  2. 2

    Design the event's fields as a stable contract, and choose Publish Immediately or Publish After Commit on purpose.

  3. 3

    Make subscribers idempotent, set a running user, and cap retries below the limit.

  4. 4

    Size publishing and delivery allocations for every external subscriber, and monitor usage.

  5. 5

    Migrate any standard-volume events before December 15, 2026.

Ready to Start

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 Call

FAQ

Frequently 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.

TC

Twopir Consulting

Salesforce Partner · HubSpot Partner

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.