EventSource HQ

This add-on is operated by EventSource HQ

Send Events From Your App to Your Users' Browsers

EventSource HQ

Last Updated: 19 March 2014

The EventSource HQ add-on is currently in beta.

Table of Contents

EventSource HQ is an add-on for sending events from your app to your users’ browsers.

Need realtime notifications? Need to synch the in-memory data in a one-page app? Need to let a user know when a long running background task has completed? EventSource HQ makes all of this trivial.

EventSource HQ is accessible via an API and has supported client libraries for Ruby, Clojure and PHP.

Sample applications

The simplest possible way to get started is to clone and deploy the sample chat application (make sure you have the heroku toolbelt installed first):

$ git clone git://
$ cd chat
$ heroku create
$ heroku addons:add eshq
$ git push heroku master

This will install an EventSource powered chat-room. The example chat application is also available in Clojure and PHP.

You can see the Sinatra app in action at

Provisioning the add-on

EventSource HQ can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add eshq
-----> Adding eshq to sharp-mountain-4005... done, v18 (free)

Once eshq has been added 3 settings will be available in the app configuration:

  • ESHQ_URL: the api endpoint
  • ESHQ_KEY: your eshq api key
  • ESHQ_SECRET: your eshq secret (never share this)

This can be confirmed using the heroku config:get command.

$ heroku config:get ESHQ_URL

After installing eshq the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export ADDON_CONFIG_NAME=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ESHQ_ values retrieved from heroku config to .env.

$ heroku config -s | grep ESHQ_ >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Client-side JavaScript API

The EventSource HQ API is very close to the HTML5 EventSource API, but instead of using an EventSource object you use the ESHQ object.

To start binding to event, create a new ESHQ channel:

var eshq = new ESHQ("my-channel");

eshq.onopen = function(e) {
    // callback called when the connection is made

eshq.onmessage = function(e) {
    // callback called when a new message has been received
    console.log("Message type: %s, message data: %s", e.type,;

eshq.onerror = function(e) {
   // callback called on errror

You can also bind to different types of event with addEventListener

eshq.addEventListener("my-event", function(e) {
    console.log("Got an event with the type 'my-event'");


When a new ESHQ connection is opened from the client, an AJAX request will be send to “/eshq/socket” with a “channel” parameter. Here you should handle any authentication needed to make sure the user should be allowed to open a connection to that channel, and then use the ESHQ client library to generate a token needed for the connection.

You can specify a different authentication endpoint by passing an auth_url to the ESHQ object:

var eshq = new ESHQ("channel", {auth_url: "/eshq-auth"});

Using with Ruby

Ruby applications will need to add the following entry into their Gemfile specifying the EventSource HQ client library.

gem 'eshq'

Update application dependencies with bundler.

$ bundle install
Installing eshq (0.0.6)

Opening a connection to a channel

You should setup a route to respond to “/eshq/socket” (unless you’ve specifyed an alternative auth_url). Here’s a simple Sinatra example:

post "/eshq/socket" do
  socket = => params[:channel])
  content_type :json
  {:socket => socket}.to_json

Sending messages to a channel

Sending events from the server is straight forward:

ESHQ.send(:channel => "my-channel", :data => "Raw Message Data", :type => "message")

The :type parameter is optional.

Using with Clojure

Add the following dependency to your project.clj file:

[clj-eshq "0.0.1"]


(require 'eshq)

;; Get a token for a channel
(eshq/open {:channel "my-channel"})

;; Send a message to a channel
(eshq/send {:channel "my-channel" :data "{\"msg\": \"Hello, World!\"}"})

Add a :type parameter to specify a specific type of event.

Using with PHP

Grab the ESHQ class from the example app: eshq.php.

Opening a connection to a channel

When the client script requests a token for a channel, use $eshq->open:

$eshq = new ESHQ();
$socket = $eshq->open(array('channel' => 'my-channel'));
echo json_encode(array('socket' => $socket));

Sending messages to a channel

Use $eshq->send to send a message:

$eshq = new ESHQ();
$eshq->send(array('channel' => 'my-channel', 'data' => 'The Data'));

Send also takes a type parameter if you want to trigger a specific type of event.


The EventSource HQ dashboard allows you to track your usage of ESHQ.

The dashboard can be accessed via the CLI:

$ heroku addons:open eshq
Opening eshq for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select EventSource HQ from the Add-ons menu.

Removing the add-on

EventSource HQ can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove eshq
-----> Removing eshq from sharp-mountain-4005... done, v20 (free)


All EventSource HQ support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at

Additional resources

Additional resources are available at: