Last updated April 28, 2023

There are two primary methods for calling into a Heroku app with an API, based on an activity in Salesforce:

• Apex HTTP callouts for programmatically making REST calls.
• Workflow outbound messages for declaratively making SOAP calls.

Either way, the Heroku app receives a request with the event details payload, and then performs the action.

When to Use

You want a REST API integration based on object updates in the Salesforce org.

Apex HTTP Callouts

With Apex callouts, you can tightly integrate your Apex with an external service, in this case, an app running on Heroku. Apex provides facilities for serializing objects into JSON and asynchronously calling HTTP endpoints. For example, here’s a helper class that can serialize an object and asynchronously POST the data to a Heroku endpoint:

public class Helper {
  public static String jsonContent(List<Object> triggerNew) {
    String newObjects = '[]';
    if (triggerNew != null) {
      newObjects = JSON.serialize(triggerNew);
    }
    String content = '{"new": ' + newObjects + '}';
    return content;
  }
  @future(callout=true) public static void callout(String url, String content) {
    Http h = new Http();
    HttpRequest req = new HttpRequest();
    req.setEndpoint(url);
    req.setMethod('POST');
    req.setHeader('Content-Type', 'application/json');
    req.setBody(content);
    h.send(req);
  }
}

You can then invoke that method by attaching a trigger:

 trigger NewContactHerokuTrigger on Contact (after insert) {
  String endpoint = 'https://example-app-1234567890ab.herokuapp.com/api/action';
  String content = Helper.jsonContent(Trigger.new);
  Helper.callout(endpoint, content);
}

Ensure that your Heroku application listens on the same API endpoint, and that it implements the appropriate action on receiving an HTTP POST. You can additionally send a session ID to allow the Heroku app to make calls back into Salesforce using the Salesforce REST API.

Outbound Messaging

With outbound messaging, you can configure Salesforce to automatically send messages (together with field values) to a designated external application endpoint, such as a Heroku app, whenever a specified set of fields change. Outbound messaging is part of the workflow rule functionality in Salesforce. Workflow rules watch for specific kinds of field changes, and trigger automatic Salesforce actions, such as sending email alerts, creating task records, or sending an outbound message.

With workflow, you declaratively define a rule and a callout to an external system. The rule can be connected to any Salesforce object.

Limits & Considerations

Calling into Heroku from Salesforce tightly couples an endpoint on Heroku with Apex code in production. This method can make debugging more difficult. For more scalable and resilient integrations, we recommend using Salesforce Platform Events.

Pay attention to API limits, as many of the scenarios described here can impact a Salesforce limit (for example, Apex Triggers have CPU time limits, which affect how often an integration can fire).

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

Learn More

• See Invoking Callouts using Apex in the Apex Developer Guide.
• See Setting Up Outbound Messaging in the SOAP API Developer Guide