Sec-WebSocket-Protocol

The HTTP Sec-WebSocket-Protocol request and response header specifies application-level subprotocols for WebSocket connections.

Baseline: Widely available

Supported across all major browsers. webstatus.dev

Table of Contents

Usage

The Sec-WebSocket-Protocol header negotiates which subprotocol the connection will use after the WebSocket handshake completes. The client sends a list of supported subprotocols ordered by preference. The server selects one from the list and returns the chosen value in the response header.

Subprotocols define application-level message formats and semantics on top of the base WebSocket framing layer. Common examples include graphql-transport-ws for GraphQL subscriptions, mqtt for IoT messaging, and chat for text-based chat protocols. Each subprotocol establishes conventions for message structure, error handling, and connection lifecycle.

When no subprotocol is needed, the header is omitted from both request and response. The connection proceeds using plain WebSocket frames without additional protocol constraints.

Values

Subprotocol name list

The request header contains a comma-delimited list of subprotocol names. The response header contains a single selected subprotocol name. Subprotocol names are case-sensitive registered tokens.

Common subprotocol values:

  • graphql-transport-ws for GraphQL subscriptions over WebSocket
  • mqtt for MQTT messaging protocol
  • wamp for Web Application Messaging Protocol
  • chat for text-based chat applications
  • stomp for Simple Text Oriented Messaging Protocol

Example

A client requesting a GraphQL subscription connection offers the graphql-transport-ws subprotocol. The server accepts the subprotocol and confirms the selection in the response.

GET /graphql HTTP/1.1
Host: api.example.re
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: graphql-transport-ws
Sec-WebSocket-Version: 13

The server response includes the selected subprotocol.

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: graphql-transport-ws

A client supporting multiple subprotocols sends a prioritized list. The server picks the first supported option.

Sec-WebSocket-Protocol: graphql-transport-ws, wamp, chat

Takeaway

The Sec-WebSocket-Protocol header enables client and server to agree on an application-level subprotocol for structured communication over WebSocket connections.

See also

Last updated: March 6, 2026