Last updated April 25, 2022

You can architect apps using an event-driven approach with the Salesforce enterprise messaging platform. Platform Events provides a powerful technique for integrating internal components within a Salesforce app, or for integrating such components with external systems, such as Heroku apps. The architecture is suitable for large distributed systems because it decouples event producers from event consumers, simplifying the communication model in connected systems.

Heroku applications can behave as event producers, event consumers, or some combination of the two.

When to Use

You want to build a modern integration with the Salesforce enterprise messaging platform. The messaging platform lets you build modular integrations with clean integration boundaries using a messaging bus, instead of point-to-point integrations.

Publishing Platform Events From Heroku

Event publication is carried out by Calling the Salesforce REST API—it’s a matter of having a Heroku application create an sObject representing the event and POSTing to the appropriate endpoint, with something like: /services/data/v43.0/sobjects/Event_Name__e/.

Using a Salesforce API client library, like JSforce for Node.js, write something like this to publish an event (in this case, a Flight_Approved event):

// Establish an authenticated Salesforce connection. (Details elided)
const conn = new jsforce.Connection({ … });

const eventData = {
  Flight_Id__c: id,
  Confirmation_Number__c: confirmationNumber
};

conn.sobject('Flight_Approved__e').create(eventData, (err, res) => {
  if (err) {
      console.error(err);
  } else {
      console.log("Event published");
  }
});

Subscribing to Platform Events

Heroku apps can subscribe to events with the CometD protocol. Salesforce sends platform events to CometD clients sequentially in the order that they’re received. The order of event notifications is based on the replay IDs of events.

In Node.js apps, for example, you can use the JSforce module to configure a subscription with replay:

// Establish an authenticated Salesforce connection. (Details elided)
const conn = new jsforce.Connection({ … });

const channel = "/event/Flight_Approved__e";
const replayId = -2; // -2 is all retained events

const replayExt = new jsforce.StreamingExtension.Replay(channel, replayId);

const fayeClient = conn.streaming.createClient([ replayExt ]);

const subscription = fayeClient.subscribe(channel, data => {
  console.log('Received Flight Approved Event', data);
});

Limits & Considerations

Read the Salesforce docs that describe what to consider when building with Platform Events, including avoiding infinite trigger loops, API limits, and more.

Security and Heroku/Salesforce integrations shows how to secure this integration.

Learn More

• Platform Events Developer Guide
• Publish Event Messages with Salesforce APIs
• Subscribe to Platform Event Notifications with CometD
• The Faye modules for Node.js and Ruby