Heroku Labs: WebSockets

Last Updated: 11 March 2014

Table of Contents

The WebSocket protocol is a core technology of modern, real-time web applications. It provides a bidirectional channel for delivering data between clients and servers. It gives you the flexibility of a TCP connection with the additional security model and meta data built into the HTTP protocol. For more details on the WebSocket protocol refer to RFC 6455.

This Heroku Labs feature adds experimental WebSocket support to your herokuapp.com domain, custom domains and custom SSL endpoints.

Features added through Heroku Labs are experimental and subject to change.

Enabling WebSockets

$ heroku labs:enable websockets -a myapp
Enabling websockets for myapp... done
WARNING: This feature is experimental and may change or be removed without notice.

Custom SSL Endpoints can be provisioned with WebSocket support. The websockets labs feature must be enabled before the endpoint has been provisioned though.

Enabling the websockets labs feature on an app with an existing SSL Endpoint will fail with the following error message:

$ heroku labs:enable websockets
Enabling websockets for myapp... failed
!    Can not add websockets feature when ssl-endpoint is in use.

Remove the existing endpoint, enable the websockets labs feature and add the SSL Endpoint add-on back again to properly provision a WebSocket capable endpoint. Remember to update the DNS records for any custom domains to point to the new hostname presented during the endpoint provisioning process.

Disabling WebSockets

$ heroku labs:disable websockets -a myapp
Disabling websockets for myapp... done

Domains and DNS configuration

When the websockets labs feature is enabled for your app, the DNS record for your herokuapp.com domain is updated to point at a WebSocket capable endpoint. It may take a moment for the DNS change to propagate. If you have custom domains attached to your app, make sure they are configured properly to ensure WebSocket support on all domains.

Application architecture

Process and application state

The WebSocket protocol introduces state into a generally stateless application architecture. It provides a mechanism for creating persistent connections to a node in a stateless system (e.g. a web browser connecting to a single web process). Because of this, each web process is required to maintain the state of its own WebSocket connections. If application data is shared across processes, global state must also be maintained.

Imagine a chat application that pushes messages from a Redis Pub/Sub channel to all of its connected users. Every web process would have a collection of persistent WebSocket connections open from active users. Each user would not, however, have its own subscription to the Redis channel. The web process would maintain a single connection to Redis, and the state of each connected user would then be updated as incoming messages arrive.

Application Diagram

In this example, web process state is maintained by your application while global state is maintained by Redis.

Visit the Add-ons Marketplace to find a Redis provider.

Security considerations

Refer to the WebSocket Security article for information on best practices.


The normal Heroku HTTP routing timeout rules apply to the WebSocket labs feature. Either client or server can prevent the connection from idling by sending an occasional ping packet over the connection.


WebSocket capable endpoints do not support HTTP keep-alive. This means that after each HTTP request, the client establishes a new connection to the endpoint. For HTTPS and WSS requests the SSL negotiation is performed for every request.

Example implementations

The following examples demonstrate the minimal code required to establish a WebSocket connection and send/receive data. Refer to the Further reading section for language specific guides for developing more powerful applications.

Further reading