Sec-WebSocket-Extensions header

BaselineWidely available

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

The HTTPSec-WebSocket-Extensionsrequest andresponse header is used in theWebSocket openinghandshake 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 separated values added to a single header.Each extension can also have one or more parameters — these are semicolon-separated values listed after the extension.

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 theWebSocket is created.

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

Syntax

http

Sec-WebSocket-Extensions: <extensions>

Directives

<extensions>: A comma-separated list of extensions to request (or for the server to agree to support).These are commonly selected from theIANA WebSocket Extension Name Registry (custom extensions may also be used).Extensions which take parameters delineate them with semicolons.

Examples

WebSocket opening handshake

The HTTP request below shows the opening handshake where a client supports thepermessage-deflate extension (withclient_max_window_bits parameter), and thebbf-usp-protocol extension.

http

GET /chat HTTP/1.1Host: example.com:8000Upgrade: websocketConnection: UpgradeSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==Sec-WebSocket-Version: 13Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits, bbf-usp-protocol

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

http

GET /chat HTTP/1.1Host: example.com:8000Upgrade: websocketConnection: UpgradeSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==Sec-WebSocket-Version: 13Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bitsSec-WebSocket-Extensions: bbf-usp-protocol

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

http

HTTP/1.1 101 Switching ProtocolsUpgrade: websocketConnection: UpgradeSec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=Sec-WebSocket-Extensions: permessage-deflate