Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
A WebSocket monitor opens a real WebSocket connection to your endpoint — the same upgrade handshake a browser performs — and, if you ask it to, sends one message and reads the reply before closing the connection. It covers both ws:// and wss://; the secure form differs only in that the connection runs over TLS.
What It Is For
Realtime endpoints users sit on all day
Chat, live dashboards, price feeds, notification channels, multiplayer game servers. These break on their own schedule: the page loads fine, and the live part of it quietly stops.
The upgrade handshake itself
Most WebSocket outages are not a dead server. A proxy, load balancer or CDN in front of it stops passing the upgrade through, or the route starts answering with an ordinary HTTP error. An HTTP monitor on the same host still reports everything green. This check either completes the handshake or it does not.
One round trip through your own protocol
Send a message after connecting — a ping frame, a subscribe command, a small JSON request — and require a piece of text in the answer. Then the check fails when the socket opens but the application behind it has stopped replying.
Sockets on odd ports and paths
The address is a full URL with a path, so a socket living at wss://example.com:8443/api/stream is checked exactly where it is, not at the site root.
What It Is Not For
The check opens one connection, exchanges at most one message, and closes. These questions need other monitors:
| You want to know | Use instead |
|---|---|
When does the certificate on a wss:// endpoint expire? This monitor records no certificate data at all — an expiring certificate stays invisible until the day it breaks the handshake | TLS/SSL certificate monitor on the same host and port, alongside this one |
| Does the site or the REST API on the same server work? | HTTP / HTTPS monitor |
| Is a plain port open, with no WebSocket handshake involved? | TCP monitor |
| Does a whole user journey still work — sign in, open the page, watch the messages arrive in a real browser? | Transaction monitor, which drives a real browser through several steps |
| Is the worker or consumer on the other side of the socket still doing its job? | Heartbeat monitor, pinged by the worker itself |
What a Check Does
- Connects to the address and performs the WebSocket upgrade handshake — for
wss://, TLS comes first. - Records the response time: the time until the connection was open. Anything after that point is not counted in it.
- If you set a message, sends it as one text frame and waits for one reply.
- If you set an expected response, checks that the reply contains that text.
- Closes the connection.
A result stores the response time, the server’s reply cut to its first 500 characters, and an error message when the check failed. Nothing else — no HTTP status, no certificate fields.
Two details are worth knowing before you rely on the message test. Only the first reply is looked at, so on a socket that greets every client with a welcome frame, that welcome is what gets compared. And if the server accepts your message and then closes the connection normally without answering, the check still passes — there is nothing to compare it against.
Status Logic
| Result | Status |
|---|---|
| The connection opened — and the reply matched, if you asked for one | UP |
| The handshake failed: the endpoint answered as ordinary HTTP, a proxy refused the upgrade, or the server rejected the request | DOWN |
| The connection was refused, the name did not resolve, or TLS failed | DOWN |
| The reply did not contain your expected text — the reply itself is saved so you can see what came back | DOWN |
| The server closed the connection with an error while the check waited for a reply | DOWN |
| The connection did not open within the timeout | TIMEOUT |
A WebSocket monitor has no middle ground: it is up, down or timed out. There is no degraded state here, so every failure above counts as downtime and can open an incident once it is confirmed.
Certificates on wss://
A wss:// check runs over TLS, but it never looks at the certificate. It reads no expiry date, no issuer and no chain details, and it stores none of them on the result.
That matters on the day the certificate expires: the handshake stops working, and the monitor goes down with a connection error — for the first time, with no warning before it. If you want to hear about it a week or two earlier, add an TLS/SSL certificate monitor pointed at the same host and port. The two monitors sit side by side: this one watches whether the socket works today, the certificate monitor watches whether it will still work next month.
Configuration
Address
The full socket URL including its path: wss://example.com/socket. A pasted http:// or https:// address is converted to ws:// or wss://, and an address with no scheme gets the one that matches the monitor type. Add the port when it is not the standard 80 for ws:// or 443 for wss://.
Message to send (optional)
Sent as a single text frame once the connection is open, up to 2048 characters. Leave it empty and the check stops at the handshake, which is already a useful signal on its own.
Expected response (optional)
A piece of text that must appear somewhere in the reply — a substring, not a full match, and upper and lower case matter. It only applies when a message is sent and the server answers. Keep it short and stable: a status word from a JSON frame survives a schema change, a whole frame does not.
Timeout
How long the connection may take to open. Default 5 seconds, from 1 to 120. A socket that needs longer than this on a good day should get a higher value, not a monitor that flaps.
Handshake extras
The handshake is a plain one: no subprotocol is negotiated and no custom headers are sent. If your endpoint needs a token to accept the connection, it has to be something the URL can carry, such as a query parameter.
Key Features
- Checks both
ws://andwss://, on any port and any path - Proves the upgrade handshake completes, which an HTTP monitor on the same host cannot do
- Optional message test with a substring assertion on the server’s reply
- The reply is saved with the result, cut to 500 characters, so a mismatch shows you what came back
- Response time measured up to the moment the connection opened
- Standard up / down / timeout behaviour, with incidents and alerts like any other monitor
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.