Sec-WebSocket-Extensions

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

The HTTP Sec-WebSocket-Extensions request and response header is used in the WebSocket opening handshake to negotiate a protocol extension used by the client and server.

In a request the header specifies one or more extensions that the web application would like to use, in order of preference. These can be added as in multiple headers, or as comma separate values added to a single header.

In a response the header can only appear once, where it specifies the extension selected by the server from the client's preferences. This value must be the first extension that the server supports from the list provided in the request header.

The request header is automatically added by the browser based on its own capabilities, and does not depend on parameters passed to the constructor when the WebSocket is created.

Header type Request header, Response header
Forbidden header name Yes (Sec- prefix)

Syntax

Request

http
Sec-WebSocket-Extensions: <extensions>

Response

http
Sec-WebSocket-Extensions: <selected-extension>

Directives

<extensions>

A comma-separated list of extensions to request (or for the server to agree to support). These should be selected from the IANA WebSocket Extension Name Registry. Extensions which take parameters delineate them with semicolons.

Examples

WebSocket opening handshake

The HTTP request below shows the opening handshake where a client supports the permessage-deflate and client_max_window_bits extensions.

http
GET /chat HTTP/1.1
Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

The request below with separate headers for each extension is equivalent:

http
GET /chat HTTP/1.1
Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate
Sec-WebSocket-Extensions: client_max_window_bits

The response below might be sent from a server to indicate that it will support the permessage-deflate extension:

http
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Extensions: permessage-deflate

Specifications

Specification
The WebSocket Protocol
# section-11.3.2

Browser compatibility

BCD tables only load in the browser

See also