Platform Events Architecture: Async by Design

Platform Events: The Event Bus Inside Salesforce

Before Platform Events (introduced in Summer '17), connecting Salesforce processes asynchronously required workarounds: custom batch jobs polling for changes, outbound messages with synchronous callbacks, or complex trigger-based queuing. Platform Events provided a native, first-class event bus built into the Salesforce platform.

A Platform Event is a special type of Salesforce object — defined in Setup like a custom object — that represents a business event. Unlike a custom object, Platform Event records are not stored in the database long-term. They are published to an event bus, retained for 72 hours for replay purposes, and delivered to all active subscribers. The event record exists for event routing, not for historical data storage.

The key architectural property is the publish-subscribe (pub/sub) decoupling. A publisher (an Apex trigger, a Flow, an API call from an external system) publishes an event without knowing who will consume it. Subscribers (an Apex trigger on the event, a Flow triggered by the event, an external system subscribed via the Streaming API) receive events without knowing who published them. The two sides are fully independent — you can add subscribers without modifying the publisher, and the publisher continues working even if no subscribers are active.

Defining and Publishing Platform Events

Platform Events are defined in Setup under Platform Events. The definition specifies the event name (always ending in __e), the custom fields that carry event payload data, and the publish behavior (which affects transaction boundaries).

There are two publish behaviors:

Publish After Commit: The event is published only after the current transaction commits. If the transaction rolls back (due to an exception or validation failure), the event is never published. This is the appropriate behavior for events that signal "something happened" — you don't want to notify downstream systems about a record creation that was ultimately rolled back.

Publish Immediately: The event is published as soon as EventBus.publish() is called, regardless of whether the current transaction commits. This is appropriate for events that must signal even during transaction failures — error notifications, audit events, or monitoring signals where you want the event published regardless of the transaction outcome.

// Define Platform Event payload fields in the event definition
// Then publish from Apex:

Order_Status_Change__e evt = new Order_Status_Change__e(
    Order_Id__c = order.Id,
    Old_Status__c = 'Draft',
    New_Status__c = 'Activated',
    Account_Id__c = order.AccountId,
    Changed_By__c = UserInfo.getUserId()
);

// Publish and check for errors
Database.SaveResult sr = EventBus.publish(evt);
if (!sr.isSuccess()) {
    for (Database.Error err : sr.getErrors()) {
        System.debug('Platform Event publish error: ' + err.getMessage());
    }
}

Publishing from Flow is simpler — a Create Records action on the Platform Event object publishes the event. From external systems, you can publish via the REST API using a POST to the Platform Event endpoint.

Event Replay and Durable Delivery

One of the most important architectural properties of Platform Events is durability. Unlike traditional message queues where a message is lost if the consumer is offline when it arrives, Platform Events are retained for 72 hours. Any subscriber that comes online within that window can request events from any point in the retention window — replaying from the beginning, from a specific event ID, or from the latest event only.

This durability has significant implications for integration architecture. External systems that subscribe via the Streaming API or the Pub/Sub API can store their last-received event replay ID and request all events since that ID on reconnection. This makes Platform Events appropriate for integration scenarios where the consumer may have downtime windows — the subscriber catches up on reconnection rather than losing events.

The 72-hour window is the boundary of the durability guarantee. Events older than 72 hours are not replayable. For scenarios requiring longer message retention or guaranteed exactly-once delivery (which Platform Events do not provide — they guarantee at-least-once delivery), a different mechanism (MuleSoft, Kafka, or a database-backed queue) may be more appropriate.

Three Consumer Patterns: Triggers, Flows, and External Subscribers

Platform Events can be consumed by three types of subscribers, each appropriate for different scenarios.

Apex Trigger on Platform Event: An Apex trigger defined on the Platform Event object (trigger handler on Order_Status_Change__e) runs as an asynchronous process. It receives a batch of event messages (up to 2,000 per transaction) and can perform DML, callouts, and complex logic. Apex event triggers do not run in the same transaction as the publisher — they are queued and executed asynchronously. This is critical: if the trigger fails, the event is not consumed, and the platform retries the trigger. Apex event triggers should be idempotent for this reason.

Flow Triggered by Platform Event: A Record-Triggered Flow (or Autolaunched Flow triggered by a Platform Event) provides a low-code option for event consumption. This is appropriate for straightforward automation — creating records, sending notifications, updating related records — where the flow logic is maintainable without code. Flow event triggers run asynchronously like Apex triggers.

External Subscriber via Streaming API / Pub/Sub API: External systems subscribe to Platform Events via the Salesforce Streaming API (CometD protocol) or the newer Pub/Sub API (gRPC-based, higher throughput). This is the pattern for integrating external applications — an ERP subscriber receives order events, an analytics platform receives data change events, a notification service receives alert events.

// Apex trigger consuming Platform Events
trigger OrderStatusHandler on Order_Status_Change__e (after insert) {
    List<Order> toUpdate = new List<Order>();

    for (Order_Status_Change__e evt : Trigger.new) {
        // Idempotent update — safe to retry
        toUpdate.add(new Order(
            Id = evt.Order_Id__c,
            Integration_Status__c = 'Notified',
            Last_Event_Time__c = evt.CreatedDate
        ));
    }

    // Use allOrNone=false — partial success is better than full failure
    Database.update(toUpdate, false);
}

Change Data Capture: Platform Events for Data Changes

Change Data Capture (CDC) is a specialised form of Platform Events automatically generated by the Salesforce platform whenever records are created, updated, deleted, or undeleted. Rather than requiring developers to manually publish events when data changes, CDC automatically generates change events for any configured object.

CDC events carry the complete change payload: the record ID, the operation type (CREATE, UPDATE, DELETE, UNDELETE), the changed field values (for updates, only the modified fields are included), and a transaction key that allows grouping multiple record changes from the same transaction.

CDC is valuable for data synchronisation scenarios: keeping an external data warehouse current with Salesforce record changes, maintaining a read replica of Salesforce data in a search index, or triggering downstream processes when specific field values change.

Performance, Limits, and High-Volume Patterns

Platform Events operate within governor limits that become architectural constraints at scale. The primary limits are:

Daily publish limit: 250,000 events per day on Enterprise Edition (higher on Unlimited Edition, and additional capacity can be purchased). This sounds large until you model a high-volume scenario: 100 users each processing 100 records per hour over an 8-hour day = 80,000 events. Add system integrations and the limit can be approached in active orgs.

Max fields per event: 100 custom fields. Events should carry the minimal payload needed to route and process — not a dump of every field on the source record. Lean event payloads also reduce the risk of hitting the event size limit (1MB per event).

Subscriber concurrency: Apex trigger subscribers process events in batches of up to 2,000. If the processing rate is slower than the publishing rate (e.g., because each event triggers expensive external API calls), the event queue depth grows. Monitor the EventBusSubscriber object to detect queue depth growth, which signals a processing bottleneck.