Keep watch on a WebSocket connection

A quick hello from your lookout

A WebSocket monitor opens a short connection to your public endpoint. With no response rules or ping requirement, a healthy result means the server completed a valid opening handshake. UptimeOwl closes the connection immediately afterward. Add a text or JSON rule to check the first complete response message instead. You can also require a matching pong or a specific subprotocol. These short checks do not test how long a connection stays open.

Set up your connection

Status confirmation, maintenance, groups, tags, pause/resume and Check now work just as they do for HTTP monitors. The timeout covers DNS, connecting, TLS when used, the handshake, any required pong and the response message when a rule is enabled. Response time measures the whole check.

1. Open Monitors and choose Add monitor. Owners and admins need permission to manage the monitor.
2. Choose WebSocket connection and enter a public ws:// or wss:// URL. Use wss:// for a TLS-protected connection. Pasting a WebSocket URL also selects the monitor type.
3. Choose your check interval and timeout, then save. Existing plan minimum intervals and monitor allowances apply.

Look for the right reply

Open Response text to require or exclude a phrase. Use JSON response to check a field with exists, equals or not equals. Both rules, when enabled, must pass on the same first complete message. Text comparisons can be case-sensitive; JSON comparisons use the exact value and type.

We inspect the first complete inbound text message only, up to 64 KiB. Fragmented text messages are assembled within that limit. An initial greeting is the first message too: we do not skip it or search later messages for a match. Binary, oversized or invalid UTF-8 messages fail the check. A missing response, early close or timeout also fails it. Keep expected phrases and JSON values free of credentials.

Send a small check message

Messages are encrypted using the same protected storage as HTTP request details. Saved values are not shown again. Keep saved details preserves the message, headers and authentication; Replace all saved details replaces the entire set; Remove saved details clears them all. Outbound text requires a configured monitor encryption key.

Use an endpoint and message designed for repeated monitoring. Messages may trigger actions in the receiving application. Choose a harmless health request rather than a command that changes customer data. Handshake-only checks never send a message. To return to handshake-only checks, remove the saved message, turn off both response rules and set Ping/pong check to No ping required.

Response bodies and outbound messages never appear in check logs. Exports omit protected messages, headers and authentication but preserve response rules, subprotocol and ping settings; imported monitors start paused. Re-enter omitted details before resuming.

1. Use a secure wss:// endpoint and enable a text or JSON response rule.
2. Open WebSocket request. Choose Set new details and enter the optional text message, up to 16 KiB. JSON can be sent as text.
3. Save the monitor. UptimeOwl sends the message once after each successful handshake and evaluates the first response.

Ask for a protocol and a pong

UptimeOwl sends one control-frame ping with a fresh identifier. Only its matching pong counts; an unrelated pong does not. This is different from an application message containing the word ping.

If text or JSON response rules are enabled too, both the first message and matching pong must pass before the shared timeout. Either may arrive first. We close the socket as soon as all required checks pass. Subprotocol names are ordinary configuration included in exports: put credentials in the protected authentication fields instead.

1. Open WebSocket protocol. Enter one optional Subprotocol, such as health.v1. The endpoint must select that exact token. Leave it blank when no protocol is required.
2. Set Ping/pong check to Require a matching pong when you want to verify control-frame responsiveness.

Keep credentials under a quiet wing

Headers and credentials use encrypted storage and are never displayed again. Headers are limited to 20 entries and 8 KiB in total. Authorization belongs in the authentication fields; Host, connection and Sec-WebSocket headers are managed by UptimeOwl.

Header-only authenticated handshake or ping checks do not need a message rule. An outgoing application message still does. To rotate credentials, choose Replace all saved details and re-enter any message or headers you want to keep. Changing the endpoint origin requires replacing or removing protected details. Saved credentials never appear in exports or response logs.

1. Use wss://, then open WebSocket request and choose Set new details or Replace all saved details.
2. Add custom headers if required, or select Bearer token or Basic authentication. Save the full set of details you want to retain.

Understand the result

A valid handshake records status code 101. With response rules or a ping requirement enabled, 101 alone is not enough: every required check must pass. Your confirmation thresholds decide when failed checks create incidents and alerts.

Redirects are never followed. Invalid TLS certificates and connection failures report failed checks. Private, loopback and reserved addresses are blocked, including when returned by DNS. Managed handshake headers cannot be overridden. The endpoint must return the requested subprotocol exactly, including letter case, or the handshake fails.

When switching between HTTP and WebSocket with saved protected details, replace or remove those details explicitly. Existing history stays in place. All plans can use these checks within their existing allowances.