WebSocket Replay
WebSocket Replay creates reusable sessions for testing WebSocket endpoints. Use it to reconnect with captured handshake details, edit messages, send new frames, and observe server responses.
Creating a Session
Create a WebSocket Replay session in two ways:
- Right-click a captured WebSocket message in WebSocket / SSE History and choose Send to WS Replay.
- Open WS Replay and create a session manually with a
ws://orwss://URL.
Manual sessions can include custom headers for cookies, authorization tokens, protocol negotiation, or application-specific handshake values.
Session Setup
| Field | Description |
|---|---|
| Name | Human-readable session label. |
| URL | WebSocket endpoint. The URL must start with ws:// or wss://. |
| Headers | Optional handshake headers sent when connecting. |
If you change the URL or headers, Ogma saves the session before opening the next connection.
Connecting
Select a session and click Connect. The connection state shows whether the socket is disconnected, connecting, open, closing, or closed.
Use Disconnect before switching targets or changing handshake details. Reconnect after editing the URL or headers to test a new server path or authenticated context.
Connecting only completes the WebSocket handshake. Many applications then require an authentication or initialization frame before they accept business messages. Use the captured first client message as a baseline, wait for its acknowledgement, and only then send your modified message. Captured cookies, signed URLs, and tokens may have expired.
Sending Messages
Use the composer to edit a payload and send it over the selected session. Text payloads are sent as WebSocket text frames.
Switch to binary mode for hexadecimal bytes. Replay first captured WebSocket message helps resend initialization, and Replay captured outbound sequence sends the captured client messages in order. Check replies in the timeline rather than assuming that sending a sequence recreated the application's state.
The protocol editor supports Raw WebSocket and managed GraphQL modes (graphql-transport-ws and legacy graphql-ws). Choose the protocol used by the target and supply its connection parameters. Preserve the original subprotocol header when required; requesting the wrong protocol can fail the upgrade.
Refresh timestamps is off by default. Enable it only for unsigned requests that need fresh timestamps: changing a signed URL or payload can invalidate its signature. Auto-reconnect retries after a disconnect, but a new connection may still need application-level authentication.
Captured messages sent from history keep their original payload as the starting point, so you can change one field at a time and compare behavior.
Message Timeline
The timeline records sent and received frames for the selected session.
| Column | Description |
|---|---|
| Direction | Whether the frame was sent by the client or received from the server. |
| Opcode | Frame type, such as text, binary, ping, pong, or close. |
| Size | Payload size. |
| Time | When Ogma observed the frame. |
Select a message to inspect its payload. JSON payloads are formatted when possible; raw content remains available for exact review.
Testing Workflow
- Capture a normal WebSocket flow in WebSocket / SSE History.
- Send an interesting client message to WS Replay.
- Reconnect and resend the original message to confirm the baseline behavior.
- Modify one field, token, ID, or command at a time.
- Record confirmed behavior in Findings or keep notes in Notes.
Troubleshooting
| Symptom | What to check |
|---|---|
| Upgrade rejected or forbidden | URL, Origin, cookies, authorization, and expired signed query values. |
| Invalid or unrequested subprotocol | Compare Upgrade Headers with the captured handshake and the selected protocol mode. |
| Connect succeeds, then closes | Inspect the system/close message and send the required initialization or authentication frame. |
| Message sent but no useful reply | Confirm subscription IDs, prior messages, authentication, and application state; WebSocket transport does not recreate a browser session automatically. |
With MCP, use the dedicated WS Replay message-list/read and disconnect tools. Captured history tools read a different transcript; see the MCP tool reference.