Platform Events Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Platform Events Developer Guide
Delivering Custom Notifications with Platform Events
Defining Your Custom Platform Event
Publishing Platform Events
Flows
Processes
Apex
Salesforce APIs
Pub/Sub API
Subscribing to Platform Events
Testing Your Platform Event in Apex
Encrypting Platform Event Messages at Rest in the Event Bus
Monitor Platform Event Publishing and Delivery Usage
Considerations
Examples
Reference
PDF

Publish Event Messages with Salesforce APIs

External apps use an API to publish platform event messages.

Publish events by inserting events in the same way that you insert sObjects. You can use any Salesforce API to create platform events, such as SOAP API, REST API, or Bulk API 2.0.

When publishing an event message, the result that the API returns contains information about whether the operation was successful and the errors encountered. If the success field is true, the publish request is queued in Salesforce and the event message is published asynchronously. For more details, see High-Volume Platform Event Persistence. If the success field is false, the event publish operation resulted in errors, which are returned in the errors field.

The returned result also contains the Id system field. The Id field value isn’t included in the event message delivered to subscribers. It isn’t used to identify an event message, and it isn’t always unique. Subscribers can use the ReplayId system field, which is included in the delivered message, to identify the position of the event in the stream.

Status Code Returned for Asynchronous Publishing

To indicate that the publish operation is asynchronous, the OPERATION_ENQUEUED status code is returned for a successful call in the response’s error field, in addition to the event UUID. This example response shows the statusCode field containing OPERATION_ENQUEUED and the message field containing the event UUID.

HTTP/1.1 201 Created 

{
  "id" : "e01xx0000000001AAA",
  "success" : true,
  "errors" : [ {
    "statusCode" : "OPERATION_ENQUEUED",
    "message" : "232fd30e-0a71-42bd-a97b-be0e329b2ded",
    "fields" : [ ]
  } ]
}

The examples in the next sections are based on a high-volume platform event.

REST API

To publish a platform event message using REST API, send a POST request to this endpoint.

/services/data/v63.0/sobjects/Event_Name__e/

Example

If you defined a platform event named Low Ink, publish event notifications by inserting Low_Ink__e data. This example creates one event of type Low_Ink__e in REST API.

REST endpoint:

/services/data/v63.0/sobjects/Low_Ink__e/

Request body:

{
   "Printer_Model__c" : "XZO-5"
}

After the platform event message is published, the REST response looks like this output. Headers are deleted for brevity.

HTTP/1.1 201 Created 

{
  "id" : "e01xx0000000001AAA",
  "success" : true,
  "errors" : [ {
    "statusCode" : "OPERATION_ENQUEUED",
    "message" : "232fd30e-0a71-42bd-a97b-be0e329b2ded",
    "fields" : [ ]
  } ]
}

REST API Composite Resource

To publish multiple platform event messages in one REST API request, use the composite resource. Send a POST request to this endpoint.

/services/data/v63.0/composite/

Add each platform event as a subrequest in the composite request body.

Example

This composite request contains two platform events in the request body.

{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Low_Ink__e",
      "referenceId": "event1",
      "body": {
        "Serial_Number__c" : "1000", 
        "Printer_Model__c" : "XZO-5"
      }
    },
    {
      "method": "POST",
      "url": "/services/data/v63.0/sobjects/Low_Ink__e",
      "referenceId": "event2",
      "body": {
        "Serial_Number__c" : "1001",
        "Printer_Model__c" : "XY-10"
      }
    }
  ]
}

After the platform event messages are published, the REST response looks like this output. Headers are deleted from this sample response.

{
  "compositeResponse" : [ {
    "body" : {
      "id" : "e01xx0000000001AAA",
      "success" : true,
      "errors" : [ {
        "statusCode" : "OPERATION_ENQUEUED",
        "message" : "436ccd6f-cc43-4861-a260-a3ffbc1bc27c",
        "fields" : [ ]
      } ]
    },
    "httpStatusCode" : 201,
    "referenceId" : "event1"
  }, {
    "body" : {
      "id" : "e01xx0000000001AAA",
      "success" : true,
      "errors" : [ {
        "statusCode" : "OPERATION_ENQUEUED",
        "message" : "85d962fb-f05c-4ccf-9ee1-ac751d0fc07f",
        "fields" : [ ]
      } ]
    },
    "httpStatusCode" : 201,
    "referenceId" : "event2"
  } ]
}

The allOrNone header in the composite REST request and in SOAP API applies only to platform events defined with the Publish After Commit option. For more information, see Platform Events and Transactions.

Note

SOAP API

To publish a platform event message using SOAP API, use the create() call.

Example

This example shows the SOAP message (using Partner API) of a request to create three platform event messages in one call. Each event has one custom field named Printer_Model__c.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:sobject.partner.soap.sforce.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="urn:partner.soap.sforce.com">
<SOAP-ENV:Header>
    <ns2:SessionHeader>
        <ns2:sessionId>00DR00000001fWV!AQMAQOshATCQ4fBaYFOTrHVixfEO6l...</ns2:sessionId>
    </ns2:SessionHeader>
    <ns2:CallOptions>
        <ns2:client>ClientApp/34.0.12i</ns2:client>
        <ns2:defaultNamespace xsi:nil="true"/>
        <ns2:returnFieldDataTypes xsi:nil="true"/>
    </ns2:CallOptions>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
    <ns2:create>
        <ns2:sObjects>
            <ns1:type>Low_Ink__e</ns1:type>
            <ns1:fieldsToNull xsi:nil="true"/>
            <ns1:Id xsi:nil="true"/>
            <Printer_Model__c>XZO-600</Printer_Model__c>
        </ns2:sObjects>
        <ns2:sObjects>
            <ns1:type>Low_Ink__e</ns1:type>
            <ns1:fieldsToNull xsi:nil="true"/>
            <ns1:Id xsi:nil="true"/>
            <Printer_Model__c>XYZ-100</Printer_Model__c>
        </ns2:sObjects>
        <ns2:sObjects>
            <ns1:type>Low_Ink__e</ns1:type>
            <ns1:fieldsToNull xsi:nil="true"/>
            <ns1:Id xsi:nil="true"/>
            <Printer_Model__c>XYZ-9000</Printer_Model__c>
        </ns2:sObjects>
    </ns2:create>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The response of the Partner SOAP API request looks something like this response. Headers are deleted for brevity.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:partner.soap.sforce.com">
<soapenv:Header>
 ...
</soapenv:Header>
<soapenv:Body>
    <createResponse>
        <result>
            <id>e00xx000000000F</id>
            <success>true</success>
            <errors>
               <message>04b8724e-e7e7-4caf-9bcd-0d14c9f97e31</message>
               <statusCode>OPERATION_ENQUEUED</statusCode>
            </errors>
        </result>
        <result>
            <id>e00xx000000000G</id>
            <success>true</success>
            <errors>
               <message>7378b9cc-d381-4150-b093-336e3a0e4018</message>
               <statusCode>OPERATION_ENQUEUED</statusCode>
            </errors>
        </result>
        <result>
            <id>e00xx000000000H</id>
            <success>true</success>
            <errors>
               <message>32da1ef3-6877-485a-8dde-1174f589e31a</message>
               <statusCode>OPERATION_ENQUEUED</statusCode>
            </errors>
        </result>
    </createResponse>
</soapenv:Body>
</soapenv:Envelope>