WebSocket Monitoring

A WebSocket monitor opens a real connection to a ws:// or wss:// endpoint, completes the protocol handshake, and optionally exchanges a message with the application behind it.

Why Not Just Use a TCP Monitor?

A TCP monitor on port 443 tells you something is listening. It cannot tell the difference between your realtime service and the load balancer in front of it answering on its behalf.

A WebSocket monitor goes further in a specific, verifiable way. The handshake requires the server to take a random key we generate, combine it with a value fixed by the protocol, hash it, and return the result. A proxy or a captive portal that answers 101 Switching Protocols to everything cannot produce that value — only something actually implementing WebSocket can. We check it on every check, and a mismatch fails the monitor.

An HTTP monitor cannot do this either: a WebSocket endpoint typically answers a plain GET with 400 or 426, so an HTTP monitor on the same URL either reports a permanent failure or has to be configured to accept an error code as success — which then accepts real errors too.

Setting One Up

1. Monitors → New Monitor
2. Set Monitor Type to WebSocket
3. Enter the full URL, e.g. wss://example.com/socket
4. Leave both message fields blank for a handshake-only check, or fill them in

Use wss:// unless the endpoint is genuinely unencrypted. As with HTTPS, we validate the certificate — an expired or untrusted one fails the check.

The Two Optional Fields

Together they turn "the socket opened" into "the application behind it is alive". A typical pair:

• Send: {"op":"subscribe","channel":"heartbeat"}
• Expect: "subscribed"

Three details worth knowing:

• The expected text is a plain substring, not a pattern. There is no regex support and this is deliberate — the same reason it is absent from keyword checks. A pathological pattern can block a probe for far longer than any timeout allows, and our probes are shared.
• Messages that do not match are ignored, not failures. An endpoint that greets you before answering still works. The check fails only if nothing matching arrives before the timeout.
• You can set an expected reply with no message to send. Plenty of feeds push a snapshot on connect, and waiting for it is a perfectly good check.

Reading a Failure

WS UPGRADE FAILED and WS CLOSED EARLY are kept apart on purpose. The first usually means a routing or proxy problem in front of your application; the second means your application accepted the connection and then dropped it. Different teams, different logs.

The most common cause of WS UPGRADE FAILED on a service that works in a browser is a reverse proxy that is not configured to pass Upgrade and Connection headers through. Browsers hit a different path or hostname often enough that this goes unnoticed.

What It Measures

The latency figure is handshake time — how long the upgrade took. It is directly comparable with an HTTPS monitor's response time on the same host. The per-check table also shows connect time, the TCP connection that preceded it: a large gap between the two says the network is fine and the application is slow, which is usually the first question worth answering.

Waiting for an expected message does not count toward the latency figure, so adding or removing a message check will not move your latency chart.

Limits

• The check reads at most 64 KB per message frame. An endpoint whose first message is larger than that fails with WS PROTOCOL ERROR.
• Subprotocols (Sec-WebSocket-Protocol) and custom headers are not configurable on a WebSocket monitor today.
• We do not respond to server pings. The connection is closed as soon as the check has its answer, which is typically well under a second.

Related Articles

• HTTP/HTTPS Monitoring
• Ping (ICMP) Monitoring — network-level reachability
• Monitor Intervals and Regions