Enterprise Messaging Platform Events

For example, a software system can send events containing information about printer ink cartridges. Subscribers can subscribe to the events to monitor printer ink levels and place orders to replace cartridges with low ink levels.

Custom Platform Events

Use custom platform events to publish and process custom notifications. For example, publish custom platform events to send order information to an order fulfillment service. Or publish custom platform events to send printer ink information that is processed by a service app.

You define a custom platform event in Salesforce in the same way that you define a custom object. Create a platform event definition by giving it a name and adding custom fields. Platform events support a subset of field types in Salesforce. See Platform Event Fields. This table lists a sample definition of custom fields for a printer ink event.

You can publish custom platform events on the Lightning Platform by using Apex or point-and-click tools, such as Process Builder and Flow Builder, or an API in external apps. Similarly, you can subscribe to an event channel either on the platform through an Apex trigger or point-and-click tools, or in external apps using the CometD-based Streaming API. When an app publishes an event message, event subscribers receive the event message and execute business logic. Using the printer ink example, a software system monitoring a printer makes an API call to publish an event when the ink is low. The printer event message contains the printer model, serial number, and ink level. After the printer sends the event message, an Apex trigger is fired in Salesforce. The trigger creates a case record to place an order for a new cartridge.

Standard Platform Events

Salesforce provides events with predefined fields, called standard platform events. An example of a standard platform event is AssetTokenEvent, which monitors OAuth 2.0 authentication activity. Another example is BatchApexErrorEvent, which reports errors encountered in batch Apex jobs.

Salesforce publishes standard platform events in response to an action that occurred in the app or errors in batch Apex jobs. You can subscribe to a standard platform event stream using the subscription mechanism that the event supports.

High-Volume Platform Events

Use high-volume platform events to publish and process millions of events efficiently and to scale your event-based apps. Previously, standard-volume events were available. In API version 45.0 and later, your new custom event definitions are high volume by default. Standard-volume events are still supported but not available for new event definitions. High-volume platform events offer better scalability than standard-volume platform events.

Note the following characteristics of high-volume platform events.

Asynchronous Publishing

For efficient processing of high loads of incoming event messages, high-volume platform events are published asynchronously. After the publishing call returns with a successful result, the publish request is queued in Salesforce. The event message isn’t always published immediately. For more information, see High-Volume Platform Event Persistence.

Separate Event Allocations

Each Salesforce edition provides default allocations and usage-based entitlements for the number of high-volume events delivered monthly to CometD clients. See Platform Event Allocations.

Starting in Spring ’21, standard-volume platform events are also published asynchronously.

Platform Events and sObjects

A platform event is a special kind of Salesforce entity, similar in many ways to an sObject. An event message is an instance of a platform event, similar to how a record is an instance of a custom or standard object. Unlike custom or standard objects, you can’t update or delete event records. You also can’t view event records in the Salesforce user interface, and platform events don’t have page layouts. When you delete a platform event definition, it’s permanently deleted.

You can set read and create permissions for platform events. Grant permissions to users in profiles or in permission sets.

Platform Events and Transactions

Platform event messages are published either immediately or after a transaction is committed, depending on the publish behavior you set in the platform event definition. Platform events defined to be published immediately don't respect transaction boundaries, but those defined to be published after a transaction is committed do. For more information, see Platform Event Fields. Note the following:

• If the platform event publish behavior is set to Publish Immediately:
  • The allOrNone header is ignored when publishing through the APIs. Some events can be published even when others fail in the same call.
  • You can't roll back published event messages, and the Apex setSavepoint() and rollback() Database class methods aren’t supported.
• If the publish behavior is set to Publish After Commit:
  • The allOrNone header value takes effect. If allOrNone is set to true, no events are published if at least one event fails in the same call.
  • You can roll back published event messages with the Apex setSavepoint() and rollback() Database class methods.
• The publishing of high-volume platform events is asynchronous. For more information, see Asynchronous Publishing.

When publishing platform events, DML limits and other Apex governor limits apply.

Event Retention in the Event Bus

High-volume platform event messages are stored for 72 hours (3 days). Standard-volume platform event messages are stored for 24 hours (1 day). You can retrieve past event messages when using CometD clients to subscribe to a channel.

Order of Events

If you publish multiple events in one publish call, the order of events in a batch is guaranteed for that publish request. So the order of event messages that are stored in the event bus and delivered to subscribers matches the order of events that are passed in the call. You can publish multiple events in several ways, including the Apex EventBus.publish method or the REST API composite resource. For events published across different requests, the order of events is not guaranteed because publish requests can be processed by different Salesforce application servers. As a result, a later request could be processed faster than an earlier request.

Salesforce assigns a replay ID value to a received platform event message and persists it in the event bus. Subscribers receive platform event messages from the event bus in the order of the replay ID.