Please update your Humly Room Display to version 2.0 or later before the end of 2026. Read more
Skip to content
  • There are no suggestions because the search field is empty.

WebSocket Connectivity Requirement for Humly Control Panel

Humly Control Panel (HCP) relies on a WebSocket connection between HCP and the devices and browsers that connect to it. If WebSocket traffic is blocked or altered by a proxy, firewall, or TLS-inspecting security gateway, Humly devices will not function correctly and the web interfaces become unstable. This article explains what must be allowed on the network, how to recognise the symptoms, and what your IT team should check. It applies to both Humly Cloud and on-premise installations.

Table of Contents
Common Use Cases
  • Deploying Humly Room Displays (HRD) or Humly Booking Devices (HBD) on a network that routes traffic through a corporate proxy.
  • Running HCP behind a TLS/SSL-inspecting security gateway or next-generation firewall.
  • Troubleshooting devices that appear unable to connect, or an Admin UI that repeatedly logs users out or reloads the login page.
  • Preparing network rules before rolling out Humly to a new site.
Why WebSocket Is Required

HCP uses a WebSocket connection for real-time communication. How a client behaves when WebSocket is unavailable depends on the client type:

  • Humly devices (HBD and HRD): These require a native WebSocket connection. They cannot fall back to any other transport. If WebSocket is blocked, the devices will not work.
  • Browsers (Admin UI, Reservations and other web interfaces): When WebSocket is unavailable, browsers fall back to SockJS HTTP polling. This keeps the interface partly working but makes it unstable — see the symptoms below.

Because the devices have no fallback, WebSocket connectivity is a hard requirement, not an optimisation.

What Must Be Allowed on the Network

WebSocket connections start as a normal HTTPS request that is then upgraded to the WebSocket protocol using an HTTP Upgrade header, to which the server responds with HTTP 101 Switching Protocols. The connection then stays open as a long-lived connection.

For HCP to work, every network component between the device/browser and HCP — proxy, firewall, and any TLS/SSL inspection — must:

  • Allow the WebSocket upgrade (the HTTP Upgrade request and the 101 Switching Protocols response) to the HCP address.
  • Preserve the Upgrade and Connection headers rather than stripping or rewriting them.
  • Allow long-lived connections to stay open, rather than terminating them after a short idle timeout.

The HCP address this must be allowed for is:

  • Humly Cloud: your cloud address, <your-cloud-id>.humly.cloud
  • On-premise: your HCP hostname and port
Symptoms of Blocked WebSocket Traffic

On Humly devices (HBD / HRD):

  • Devices fail to connect to HCP, or do not come online during setup.

In the browser interfaces (Admin UI, Reservations):

  • Users are logged out unexpectedly.
  • The login page reloads repeatedly.
  • Timeouts and general instability when using the interface.

These browser symptoms are the result of the SockJS polling fallback that activates when WebSocket is blocked.

What to Check and How to Resolve It

The most common causes are a corporate proxy or a TLS-inspecting security gateway that blocks the WebSocket upgrade or terminates the long-lived connection. Your IT team should:

  1. Add an exception for the HCP domain (<your-cloud-id>.humly.cloud, or your on-premise HCP hostname) in the proxy so WebSocket upgrades are allowed through.
  2. Exclude the HCP domain from TLS/SSL inspection, or configure the inspection engine to permit WebSocket upgrades and preserve the Upgrade and Connection headers.
  3. Ensure the firewall allows the WebSocket connection to the HCP address and does not close long-lived connections after a short idle period.
  4. Confirm that any load balancer or reverse proxy in the path (on-premise deployments) is configured to pass through WebSocket upgrades.
Best Practices
  • Allow WebSocket before deployment. Add the HCP domain to proxy, firewall and SSL-inspection exceptions before rolling out devices, so the first connection succeeds.
  • Treat devices and browsers differently. A working Admin UI does not prove WebSocket is allowed — the browser may be running on the degraded SockJS fallback while devices, which have no fallback, still fail.
  • Exclude the HCP domain from TLS inspection. SSL-inspecting gateways are a frequent cause; a domain exception is usually the cleanest fix.
  • Avoid short idle timeouts. Make sure proxies and firewalls do not drop the long-lived WebSocket connection after a brief period of inactivity.
  • Apply the same rules at every site. The requirement is identical for Humly Cloud and on-premise installations.
Troubleshooting

Devices will not come online, but the Admin UI works

This is a classic sign of blocked WebSocket. The browser has fallen back to SockJS polling, so the Admin UI partly works, while the devices — which require WebSocket and have no fallback — cannot connect. Check the proxy, firewall and SSL inspection for the HCP domain as described above.

The Admin UI logs users out, reloads the login page, or times out

These are symptoms of the SockJS fallback caused by blocked WebSocket. Allowing the WebSocket upgrade to the HCP domain through the proxy and SSL inspection resolves the instability.

Everything worked until a network or security change

If HCP was stable and then devices or the UI began failing, check for a recent change to the proxy, firewall, or the introduction of a TLS-inspecting gateway. Re-apply the HCP domain exception so WebSocket upgrades pass through.

How to confirm WebSocket is the cause

Have your IT team verify that an HTTP Upgrade request to the HCP address receives an HTTP 101 Switching Protocols response and that the connection stays open. If the upgrade is blocked, rewritten, or quickly closed, the network path is the cause.

Need Help?

If WebSocket traffic is allowed and the issue persists, contact Humly support at support@humly.com with a description of your network setup (proxy, firewall, and any TLS inspection in use).