Getting Started with Heroku Events (Pilot)

Introduction

Heroku Events integrates your apps with Heroku’s real-time eventing platform. This guide helps you set up the Heroku Events add-on via the Heroku CLI and the Heroku Events CLI plugin. To get an idea of what you can use Heroku Events for, read about the use cases.

In this guide, we authorize a Salesforce org, subscribe to platform events and change data capture events, and publish to platform events, Data Cloud, and a webhook.

This guide assumes that you have:

• A verified Heroku Account
• Joined the Heroku Events pilot
• An Eco dynos plan subscription (recommended)
• All the dependencies based on your language of choice
• A Salesforce sandbox org or scratch org
• (Optional) Data Cloud enabled in your sandbox org
• (Optional) Install the Salesforce CLI to work with your Salesforce org

Install the Heroku Events Plugin

You must have the Heroku CLI installed before adding the Heroku Events CLI plugin. See Heroku CLI for instructions.

To install the plugin, run the CLI command:

$ heroku plugins:install @heroku-cli/plugin-events

Provision the Heroku Events Add-on

First, create an app on Heroku:

$ heroku create herokuevents-app

Creating ⬢ herokuevents-app... done
https://herokuevents-app.herokuapp.com/ | https://git.heroku.com/herokuevents-app.git

Then provision the Heroku Events add-on:

$ heroku addons:create herokuevents -a herokuevents-app

Creating herokuevents on ⬢ herokuevents-app... free
Your Heroku Events add-on is being provisioned and will be available shortly. Add-on id: fec92a0d-4065-4780-b0cb-da61fb842e0b.
herokuevents-asymmetrical-03314 is being created in the background. The app will restart when complete...
Use heroku addons:info herokuevents-asymmetrical-03314 to check creation progress
Use heroku addons:docs herokuevents to view documentation

Add Sample Ruby Heroku App

If your Heroku app is a worker app, you can pull from events every five seconds. It requires adding the excon client to our sample Ruby app.

client = Excon.new(ENV['HEROKUEVENTS_SUBSCRIBE_URL'])

loop do
 resp = client.get(path: '/accounts')

 raise :wait unless resp.status == 200

 puts resp.body

rescue
   puts "Waiting..."
   sleep 5
end

To listen to the events, you can use a webhook receiver. In this example, the webhook receiver is the post '/contacts' path.

%w{date excon json sinatra}.each {|l| require l}
get '/' do
 '<a href="/click">Click Me!</a>'
end
post '/contacts' do
 puts request.body.read
end
get '/click' do
 Excon.post("#{ENV['HEROKUEVENTS_PUBLISH_URL']}/clicks", body: {
     id: rand(10000),
     createdate: DateTime.now.strftime('%Y-%m-%dT%H:%M:%SZ'),
     eventtype: 'add to cart',
     firstname: 'Web',
     lastname: 'Site',
 }.to_json)
 "OK"
end

Authorize a Salesforce Org

Authorize your Salesforce org that you want to subscribe and publish events to. To authorize to a sandbox org, run the command:

$ heroku events:authorizations:salesforce:create example-org --sandbox -a herokuevents-app

Opening browser to https://creds-virginia.events.heroku.com/salesforce/oauth/6c14f08c-df5d-49fe-af28-f77bfb9c5555
Press any key to open up the browser to authorize ⬢ herokuevents-app or q to exit:
Continue in your browser...

When you authorize your org for the first time, a browser window appears for you to log in with your Salesforce credentials.

To view your authorizations, run the command:

$ heroku events:authorizations -a example-app
=== Heroku Events authorizations for app ⬢ example-app

Platform   Alias
────────── ───────────
Salesforce example-org

Subscribe to Platform Events in Salesforce

This example creates a subscription that subscribes to a platform event, which has a channel name /event/Low_Ink__e. You can replace the channel name with the event you want to subscribe to in your org.

1. Subscribe to the event with events:subscriptions:salesforce:create. Here we subscribe to the Low_Ink__e platform event and name the subscription LowInkEvents on the example-org we authenticated. We’re also filtering for specific events with Printer in the name.

   During pilot, filters are supported only at the stream level. If you add a filter, the source or subscription information is mandatory, and Heroku automatically creates a stream for you.

   $ heroku events:subscriptions:salesforce:create LowInkEvents -t "/event/Low_Ink__e" -f "this.data.Name==\"Printer\"" -a herokuevents-app -A example-org
   
   Creating subscription LowInkEvents... done
   

2. Generate a new platform event for this channel using one of the ways described here.

3. Now you can make a GET request with curl to get the events by using the HEROKUEVENTS_SUBSCRIBE_URL config var and appending the subscription name.

   $ curl $(heroku config:get HEROKUEVENTS_SUBSCRIBE_URL -a herokuevents-app)/LowInkEvents
   
   ​​{"specversion":"1.0","id":"79db622d-631b-4949-9cf8-fce595a09cea","source":"","type":"","subject":"/event/Low_Ink__e","datacontenttype":"application/json","data":{"CreatedById":"0054w00000AR3X0AAL","CreatedDate":1733255456517,"Name__c":{"string":"John"}},"salesforcereplayid":"AAAAAACqSe0AAA=="}
   

After creating your platform event subscription with Heroku Events, you can also publish to this platform event.

To view the events your app is subscribed to, run the command:

$ heroku events:subscriptions -a herokuevents-app
=== Heroku Events subscriptions for app ⬢ herokuevents-app

 Name               Platform   Alias
 ────────────────── ────────── ───────────
 AccountChangeEvent Salesforce example-org

Subscribe to Change Data Capture Events in Salesforce

This example creates a subscription that subscribes to CDC events for the account object, which has a channel name /data/AccountChangeEvent. You can replace the channel name with the object you want to subscribe to in your org.

1. Enable CDC on the account object in Salesforce.

2. Subscribe to the event with events:subscriptions:salesforce:create. Here we subscribe to account change events and name the subscription AccountEvents on the example-org we authenticated.

   $ heroku events:subscriptions:salesforce:create AccountEvents -t "/data/AccountChangeEvent" -a herokuevents-app -A example-org
   
   Creating subscription AccountEvents... done
   

3. Make any change to an account record in Salesforce so it creates a change event.

4. Now you can make a GET request with curl to get the events by using the HEROKUEVENTS_SUBSCRIBE_URL config var and appending the subscription name.

   $ curl $(heroku config:get HEROKUEVENTS_SUBSCRIBE_URL -a herokuevents-app)/AccountEvents
   
   {"specversion":"1.0","id":"a6377840-cc46-47ff-8e2e-ca144d3ee582","source":"","type":"","subject":"/data/AccountChangeEvent","datacontenttype":"application/json","data":{"AccountNumber":null,"AccountSource":null,"AnnualRevenue":null,"BillingAddress":null,"ChangeEventHeader":{"changeOrigin":"com/salesforce/api/soap/63.0;client=SfdcInternalAPI/","changeType":"UPDATE","changedFields":["0x400002"],"commitNumber":1733958929815166978,"commitTimestamp":1733958929000,"commitUser":"005Ws000001eUtGIAU","diffFields":[],"entityName":"Account","nulledFields":[],"recordIds":["001Ws00003SFoKbIAL"],"sequenceNumber":1,"transactionKey":"0000256b-9849-95e8-d113-e4ac339c6383"},"CreatedById":null,"CreatedDate":null,"Description":null,"Fax":null,"Industry":null,"Jigsaw":null,"JigsawCompanyId":null,"LastModifiedById":null,"LastModifiedDate":{"long":1733958929000},"Name":{"string":"My Account CDC2"},"NumberOfEmployees":null,"OwnerId":null,"Ownership":null,"ParentId":null,"Phone":null,"Rating":null,"ShippingAddress":null,"Sic":null,"SicDesc":null,"Site":null,"TickerSymbol":null,"Type":null,"Website":null},"salesforcereplayid":"AAAAAAAH5qQAAA=="}
   

To see the info on a subscription, run the command:

$ heroku events:subscriptions:info AccountChangeEvent -a herokuevents-app
Alias:    example-org
Id:       469fc380-dd0c-4ca4-b5f8-4fa4c9a91076
Name:     AccountChangeEvent
Platform: Salesforce
Topics:   ["/data/AccountChangeEvent"]

Publish Events to Salesforce

 

Heroku Events also makes it easy for your application to publish events in Salesforce.

This example creates a publication that publishes to a platform event, which has a channel name /event/Low_Ink__e. You can replace the channel name with the event you want to publish to in your org.

1. Publish to the event with events:publications:salesforce:create. Here we create a publication named LowInkPub that publishes Low_Ink__e events to Salesforce.

   $ heroku events:publications:salesforce:create LowInkPub -t "/event/Low_Ink__e" -a herokuevents-app -A example-org
   

2. Get the base URL that the add-on sets in the HEROKUEVENTS_PUBLISH_URL config var.

   $ heroku config:get HEROKUEVENTS_PUBLISH_URL -a herokuevents-app
   

3. Provide the event data by sending the POST request to the base URL with the name of the publication appended to it. The request body contains the fields and values in JSON format.

   $ curl -X POST $(heroku config:get HEROKUEVENTS_PUBLISH_URL -a herokuevents-app)/LowInkPub \
     --header "Content-Type: application/json" \
     --data '{"field1": {"string": "value1"}}'
   

To view the events your app has published, run the command:

$ heroku events:publications -a herokuevents-app
=== Heroku Events publications for app ⬢ herokuevents-app

 Name         Platform   Alias
 ──────────── ────────── ───────────
 systemStatus Salesforce example-org

To see the info on a publication, run the command:

$ heroku events:publications:info systemStatus -a herokuevents-app
Alias:    example-org
Filter:
Id:       af3d1a0d-ad29-4e3f-ad06-31195b99bae8
Name:     systemStatus
Platform: Salesforce
Topic:    /event/System_Status__e

Publish Events to Data Cloud

 

This example creates a publication that publishes events to Data Cloud using the Ingestion API connector named Heroku_Click_Ingestion You can replace the connector name with the connector you want to publish to in your org.

1. Set up an Ingestion API connector in Data Cloud.

2. Publish to the event with events:publications:datacloud:create. Here we create a publication named herokuclickevent that publishes events to the Heroku_Click_Ingestion connector in the example-org org we authorized.

   $ heroku events:publications:datacloud:create herokuclickevent -A example-org -a herokuevents-app -c "Heroku_Click_Ingestion" --object=heroku_app_clicks
   

Publish Events to a Webhook

 

This example uses a Salesforce subscription with a platform event or CDC event and publishes events to a webhook endpoint.

1. You must implement the <WEBHOOK_URL> endpoint to act on the incoming data. For example, you can deploy a simple server to Heroku that receives webhook requests and logs them. The Getting Started on Heroku page has starting points for all of Heroku’s supported languages.

2. Publish to the webhook with heroku events:publications:webhook:create. Here we create a publication named event-webhook that publishes events to the https://webhook.site/filter webhook URL using the LowInkEvents subscription we created. We’re also filtering for specific events from accounts named Acme. Optionally, you can also add an <ACCESS_TOKEN> for your webhook URL.

   $ heroku events:publications:webhook:create event-webhook -a herokuevents-app -f "this.data.Name==\"Acme\"" -u "https://webhook.site/filter" -s AccountChangeEvent -t <ACCESS_TOKEN>
   

3. Link the LowInkEvents subscription and the webhookpubevent publication to create an event stream.

   $ heroku events:streams:create LowInkEvents webhookpubevent -a herokuevents-app
   

Delete Your Authorizations, Subscriptions, Publications, and Add-on

Remove an Authorization

When you remove an authorization, any subscriptions and publications using the authorization will fail. To remove an authorization from a Salesforce org, run the command:

$ heroku events:authorizations:destroy example-org -a herokuevents-app
 ›   Warning: Destructive Action.
 ›   This command will affect the app herokuevents-app.

To proceed, type herokuevents-app or re-run this command with --confirm herokuevents-app: herokuevents-app
Destroying authorization example-events on ⬢ herokuevents-app... !

Delete a Subscription

To stop subscribing to an event, run the command:

$ heroku events:subscriptions:destroy AccountChangeEvent -a herokuevents-app
Destroying subscription AccountChangeEvent on herokuevents-app

Delete a Publication

To delete a publication, run the command:

$ heroku events:publications:destroy systemStatus -a herokuevents-app
Destroying publication systemStatus on herokuevents-app

Removing the Add-on

To remove your Heroku Events add-on, run the command:

$ heroku addons:destroy herokuevents

Next Steps

Here’s some recommended reading:

• Integrating with Salesforce
• Salesforce Developers: Get Started Ingestion API
• Salesforce Developers: Webhook Data Action Targets in Data Cloud
• Heroku AppLink and Heroku Events Samples
• Getting Started with Heroku AppLink (Pilot)