Identify and Match Event Messages with the EventUuid Field

Delivered platform event messages include the EventUuid field, which identifies an event message. Use this field to match published and received event messages by comparing the universally unique identifiers (UUIDs) of the received events with the UUIDs returned in the SaveResult of publish calls. This way, you can find any event messages that aren’t delivered and republish them.

If you use Apex to publish events, use Apex publish callbacks to track the final result of the EventBus.publish call. For more information, see Get the Result of Asynchronous Platform Event Publishing with Apex Publish Callbacks.

Note

The EventUuid field is a universally unique identifier (UUID) that identifies a platform event message. The system populates the EventUuid field, and you can’t overwrite its value. The EventUuid field is available in CometD clients using API version 52.0 and later. The API version corresponds to the version that an Apex trigger is saved with or the version specified in a CometD subscriber endpoint. The EventUuid field isn’t part of the event schema, which is returned by the REST eventSchema resource or the describe call result. The EventUuid field is available for high-volume and standard-volume platform events.

For Pub/Sub API clients, the event id field contains the event UUID value. There’s no field named EventUuid. The id field is present in all Pub/Sub API clients, isn’t versioned, and can be overwritten. For more information, see the PublishStream RPC Method in the Pub/Sub API documentation.

For all publishing methods except for Pub/Sub API, event publishing is asynchronous. A success status in an immediately returned SaveResult means that the publish operation is queued in Salesforce. The operation is carried out later when system resources are available. Some failures, such as validation or limit errors, are returned in the SaveResult, but not asynchronous errors. In rare cases, enqueued publish operations can fail due to a system error, and the event message isn’t delivered. You can use the EventUuid field to determine which enqueued event messages failed to publish and then republish them.

Publishing with Pub/Sub API is synchronous and the returned response contains the final publishing status.

Get the Event UUID of Published Event Messages

Before you can compare the UUIDs of published and received event messages, first save the UUID of published event messages. Also, save the corresponding event field values so that you can republish the events if needed.

If you publish the event using Salesforce APIs, the SaveResult returned contains the UUID in the Error message field. This example contains the save result of an event inserted using a REST API POST request.

1{
2  "id" : "e01xx0000000001AAA",
3  "success" : true,
4  "errors" : [ {
5    "statusCode" : "OPERATION_ENQUEUED",
6    "message" : "e981b488-81f3-4fcc-bd6f-f7033c9d7ac3",
7    "fields" : [ ]
8  } ]
9}

If you publish the event in Apex, you can obtain the UUID by calling this method: EventBus.getOperationId(saveResult).

This example gets the UUID from the event publish call using Apex.

Prerequisites: Before you can run this example, define a platform event with the label of Order Event and these fields: Order Number of type Text(10) and Has Shipped of type Checkbox.

1// Publish a high-volume event message
2Order_Event__e evt = new Order_Event__e(
3    Order_Number__c='17',
4    Has_Shipped__c = false);
5Database.SaveResult sr = EventBus.publish(evt);
6// Inspect immediate result
7if (sr.isSuccess() == true) {
8    System.debug('Successfully enqueued event for publishing.');
9    // Get the UUID that uniquely identifies this event publish
10    System.debug('UUID=' + EventBus.getOperationId(sr));
11} else {
12   for(Database.Error err : sr.getErrors()) {
13       System.debug('Error returned: ' +
14                    err.getStatusCode() +
15                    ' - ' +
16                    err.getMessage());
17   }
18}
19 
20// Debug message output:
21//|DEBUG|Successfully enqueued event for publishing.
22//|DEBUG|UUID=6ba5db7e-c27b-4a67-a3c5-cf425ffcaf53

Get the Event UUID from Received Event Messages in a CometD Client

In a CometD client, the received event message contains the event UUID in the EventUuid field in the event subsection, as shown in this JSON event example.

1{
2  "schema": "UIovjRagY-xEDIJ1Ehzafg",
3  "payload": {
4    "CreatedDate": "2021-03-04T18:31:40.517Z",
5    "CreatedById": "005RM00000231cZYAQ",
6    "Order_Number__c": "17",
7    "Has_Shipped__c": false
8  },
9  "event": {
10     "EventUuid": "e981b488-81f3-4fcc-bd6f-f7033c9d7ac3",
11     "replayId": 617
12  }
13}

Get the Event UUID from Received Event Messages in a Pub/Sub API Client

In a Pub/Sub API client, the received event message contains the event UUID value in the id field of the event instance. For example, you can retrieve the UUID value in your code by accessing the id field on the event instance as follows.

1event.id

The returned value is a UUID similar to this example.

14c45a27a-5d86-47ed-881a-878b9a9c0dcc

Get the Event UUID from Received Event Messages in an Apex Trigger

In an Apex trigger, extract the event UUID by accessing the EventUuid field on the event object.

1trigger OrderEventTrigger on Order_Event__e (after insert) {
2    for(Order_Event__e evt: Trigger.New) {
3        // Get the event UUID
4        String EventUuid = evt.EventUuid;
5        System.debug('Received event UUID=' + EventUuid);
6
7        // Store the event UUID for matching with published event UUID
8        // . . .
9    }
10}
11
12// Debug message output:
13//|DEBUG|Received event UUID=6ba5db7e-c27b-4a67-a3c5-cf425ffcaf53

Match UUIDs of Published and Received Event Messages

After you obtain the event UUIDs for both published and received event messages, match the UUIDs. Any UUIDs that don’t match can indicate that the event hasn’t been delivered. You can attempt to republish the unmatched event messages.

Platform Events Developer Guide