OpenUptime

WebSocket monitors

A WebSocket monitor opens a connection to a ws:// or wss:// URL and checks that the server accepts it. You can also send a message and check what comes back.

Handshake

Every check starts with the opening handshake. The check passes when the server answers 101 Switching Protocols with a correct Sec-WebSocket-Accept header. Anything else fails the check, with the reason in the result:

  • another status, such as 401 or 404: "Expected 101 Switching Protocols, got 404";
  • a redirect: redirects are not followed, and the error names where it pointed;
  • a wrong accept header, a refused connection, a TLS error or no answer within the timeout.

With only a URL, that is the whole check: the connection is then closed normally (code 1000). The recorded latency is the time to complete the handshake.

Send a message

Fill in Message to send (up to 2000 characters) and the monitor sends it as a text frame once the connection is open. It then waits for the next message from the server. The check fails if the server closes the connection first, with the close code and reason in the error, or if nothing arrives within the timeout. The recorded latency then runs until the reply arrives.

For a server that speaks first, such as one that sends a greeting or a snapshot on connect, leave the message empty and set a keyword: the monitor waits for the first message instead.

Check the reply

Set a keyword to look for in the reply (or in the first message when nothing is sent). Contains fails the check when the keyword is missing; absent fails it when the keyword is present, which suits a reply such as "status":"error". The keyword is matched as plain text, case-sensitive. Binary messages are read as UTF-8, and the first 1 MB of a message is checked; a single frame larger than 1 MB fails the check.

Headers and authentication

Headers you add are sent with the handshake request, so a token goes in Authorization or a cookie header. Header values are masked for members who cannot manage monitors. The message to send is not: anyone who can see the monitor can read it, so keep credentials out of it. The headers the handshake itself needs (Connection, Upgrade, Host and the Sec-WebSocket-* ones) cannot be overridden.

Timeout and regions

The monitor's timeout covers the whole check: connecting, the handshake and waiting for a reply. WebSocket monitors can be checked from several regions, like HTTP and TCP monitors. If you run your own probes, update them before choosing regions for a WebSocket monitor: an older probe refuses the check and its region shows as unreachable.

Docker and Cloudflare Workers

The check works the same way in both deployments. On Docker and Node, addresses that resolve to private networks are refused unless ALLOW_PRIVATE_TARGETS is set, as for other monitors. On Cloudflare Workers the platform makes the connection, and it refuses private addresses itself.

WebSocket 监控

WebSocket 监控会连接一个 ws:// 或 wss:// 地址，检查服务器是否接受连接。你还可以发送一条消息，并检查返回的内容。

握手

每次检测都从握手开始。服务器返回 101 Switching Protocols 且 Sec-WebSocket-Accept 正确时，检测通过。其他情况都会判定失败，并在结果中写明原因：

  • 返回其他状态码，例如 401 或 404：“Expected 101 Switching Protocols, got 404”；
  • 重定向：不会跟随重定向，错误信息会写明跳转地址；
  • Accept 头不正确、连接被拒绝、TLS 出错，或在超时时间内没有响应。

只填写地址时，握手成功即检测完成，随后正常关闭连接（关闭码 1000）。记录的延迟是完成握手所用的时间。

发送消息

填写 要发送的消息（最多 2000 个字符）后，连接建立后会以文本帧发出这条消息，然后等待服务器的下一条消息。如果服务器先关闭了连接（错误信息中会带上关闭码和原因），或在超时时间内没有收到消息，检测失败。此时记录的延迟会一直计到收到回复为止。

如果服务器会主动先发消息，例如连上就推送欢迎语或数据快照，可以不填消息、只设置关键词，监控会等待收到的第一条消息。

校验回复

设置关键词后，会在回复中（未发送消息时则在第一条消息中）查找它。包含模式下找不到关键词即失败；不包含模式下出现关键词即失败，适合 "status":"error" 这类回复。关键词按纯文本匹配，区分大小写。二进制消息按 UTF-8 读取，只检查消息的前 1 MB；单个帧超过 1 MB 时检测失败。

请求头与认证

你添加的请求头会随握手请求一起发送，令牌可以放在 Authorization 或 Cookie 头中。对没有监控管理权限的成员，请求头的值会被遮盖。要发送的消息则不会：能看到监控的人都能看到它，请不要在其中放凭据。握手本身需要的请求头（Connection、Upgrade、Host 以及各个 Sec-WebSocket-*）不能被覆盖。

超时与区域

监控的超时时间覆盖整次检测：建立连接、握手以及等待回复。和 HTTP、TCP 监控一样，WebSocket 监控也可以从多个区域检测。如果你运行自己的探针，请先更新探针再为 WebSocket 监控选择区域：旧版探针会拒绝这类检测，对应区域会显示为无法连通。

Docker 与 Cloudflare Workers

两种部署方式下检测行为一致。在 Docker 和 Node 上，解析到内网地址的目标默认会被拒绝，除非设置了 ALLOW_PRIVATE_TARGETS，与其他监控相同。在 Cloudflare Workers 上由平台发起连接，平台本身会拒绝内网地址。

Last updated 2026-10-28最后更新：2026-10-28