webRequest API

Hint

The webRequest API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Use the browser.webRequest API to observe and analyze traffic and to intercept, block, or modify requests in-flight.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

webRequest

webRequest

Grant access to some or all methods of the webRequest API.

webRequestBlocking

webRequestBlocking

Allows to use the blocking features of the webRequest API. With this permission, listeners can synchronously modify or cancel requests before they are sent or before a response is delivered. Without it, listeners can only observe requests without blocking or altering them.

Note

The permission webRequest is required to use messenger.webRequest.*.

Functions

filterResponseData(requestId)

– [Added in TB 57]

Parameters

requestId

requestId

(string)

Return type (Promise)

_returns

Required permissions

  • webRequest

  • webRequestBlocking

getSecurityInfo(requestId, [options])

– [Added in TB 62]

Retrieves the security information for the request. Returns a promise that will resolve to a SecurityInfo object.

Parameters

requestId

requestId

(string)

options

[options]

(object, optional)

certificateChain

[certificateChain]

(boolean, optional)

Include the entire certificate chain.

rawDER

[rawDER]

(boolean, optional)

Include raw certificate data for processing by the extension.

Required permissions

  • webRequest

handlerBehaviorChanged()

Needs to be called when the behavior of the webRequest handlers has changed to prevent incorrect handling due to caching. This function call is expensive. Don’t call it often.

Required permissions

  • webRequest

Events

onAuthRequired

– [Added in TB 54]

Fired when an authentication failure is received. The listener has three options: it can provide authentication credentials, it can cancel the request and display the error page, or it can take no action on the challenge. If bad user credentials are provided, this may be called multiple times for the same request.

Note

To handle a request asynchronously, return a Promise from the listener.

Parameters for onAuthRequired.addListener(listener, filter, extraInfoSpec)

listener(details, asyncCallback)

listener(details, asyncCallback)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnAuthRequiredOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

challenger

challenger

(object)

The server requesting authentication.

Note

Before version 57, when authenticating to a proxy server, the challenger.host property contains the hostname for the requested URL rather than the hostname for the proxy.

host

host

(string)

port

port

(integer)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

isProxy

isProxy

(boolean)

True for Proxy-Authenticate, false for WWW-Authenticate.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

scheme

scheme

(string)

The authentication scheme, e.g. Basic or Digest.

statusCode

statusCode

(integer)

Standard HTTP status code returned by the server.

statusLine

statusLine

(string)

HTTP status line of the response or the ‘HTTP/0.9 200 OK’ string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

originUrl

[originUrl]

(string, optional)

URL of the resource that triggered this request.

realm

[realm]

(string, optional)

The authentication realm provided by the server, if there is one.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

The HTTP response headers that were received along with this response.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

asyncCallback

[asyncCallback]

(function, optional)

Expected return value of the listener function

web-request-on-auth-required-returns

If “blocking” is specified in the “extraInfoSpec” parameter, the event listener should return an object of this type.

Required permissions

  • webRequest

onBeforeRedirect

– [Added in TB 46]

Fired when a server-initiated redirect is about to occur.

Parameters for onBeforeRedirect.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnBeforeRedirectOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

fromCache

fromCache

(boolean)

Indicates if this response was fetched from disk cache.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

redirectUrl

redirectUrl

(string)

The new URL.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

statusCode

statusCode

(integer)

Standard HTTP status code returned by the server.

statusLine

statusLine

(string)

HTTP status line of the response or the ‘HTTP/0.9 200 OK’ string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

ip

[ip]

(string, optional)

The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

The HTTP response headers that were received along with this redirect.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Required permissions

  • webRequest

onBeforeRequest

– [Added in TB 46]

Fired when a request is about to occur.

Note

Asynchronous event listeners are supported from version 52.

Parameters for onBeforeRequest.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnBeforeRequestOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

requestBody

[requestBody]

(object, optional)

– [Added in TB 53]

Contains the HTTP request body data. Only provided if extraInfoSpec contains ‘requestBody’.

error

[error]

(string, optional)

Errors when obtaining request body data.

formData

[formData]

(object, optional)

If the request method is POST and the body is a sequence of key-value pairs encoded in UTF8, encoded as either multipart/form-data, or application/x-www-form-urlencoded, this dictionary is present and for each key contains the list of all values for that key. If the data is of another media type, or if it is malformed, the dictionary is not present. An example value of this dictionary is {‘key’: [‘value1’, ‘value2’]}.

raw

[raw]

(array of UploadData, optional)

If the request method is PUT or POST, and the body is not already parsed in formData, then the unparsed request body elements are contained in this array.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Expected return value of the listener function

web-request-on-before-request-returns

If “blocking” is specified in the “extraInfoSpec” parameter, the event listener should return an object of this type.

Required permissions

  • webRequest

onBeforeSendHeaders

– [Added in TB 45]

Fired before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any HTTP data is sent.

Note

Asynchronous event listeners are supported from version 52.

Parameters for onBeforeSendHeaders.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnBeforeSendHeadersOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

requestHeaders

[requestHeaders]

(HttpHeaders, optional)

– [Added in TB 53]

The HTTP request headers that are going to be sent out with this request.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Expected return value of the listener function

web-request-on-before-send-headers-returns

If “blocking” is specified in the “extraInfoSpec” parameter, the event listener should return an object of this type.

Required permissions

  • webRequest

onCompleted

– [Added in TB 45]

Fired when a request is completed.

Parameters for onCompleted.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnCompletedOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

fromCache

fromCache

(boolean)

Indicates if this response was fetched from disk cache.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

requestSize

requestSize

(integer)

For http requests, the bytes transferred in the request. Only available in onCompleted.

responseSize

responseSize

(integer)

For http requests, the bytes received in the request. Only available in onCompleted.

statusCode

statusCode

(integer)

Standard HTTP status code returned by the server.

statusLine

statusLine

(string)

HTTP status line of the response or the ‘HTTP/0.9 200 OK’ string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

urlClassification

urlClassification

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

ip

[ip]

(string, optional)

The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

The HTTP response headers that were received along with this response.

Required permissions

  • webRequest

onErrorOccurred

– [Added in TB 45]

Fired when an error occurs.

Parameters for onErrorOccurred.addListener(listener, filter)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

Parameters passed to the listener function

details

details

(object)

error

error

(string)

The error description. This string is not guaranteed to remain backwards compatible between releases. You must not parse and act based upon its content.

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

fromCache

fromCache

(boolean)

Indicates if this response was fetched from disk cache.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

ip

[ip]

(string, optional)

The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Required permissions

  • webRequest

onHeadersReceived

– [Added in TB 45]

Fired when HTTP response headers of a request have been received.

Note

Modification of the ‘Content-Type’ header is supported from version 51.

Note

Asynchronous event listeners are supported from version 52.

Parameters for onHeadersReceived.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnHeadersReceivedOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

statusCode

statusCode

(integer)

Standard HTTP status code returned by the server.

statusLine

statusLine

(string)

HTTP status line of the response or the ‘HTTP/0.9 200 OK’ string for HTTP/0.9 responses (i.e., responses that lack a status line).

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

The HTTP response headers that have been received with this response.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Expected return value of the listener function

web-request-on-headers-received-returns

If “blocking” is specified in the “extraInfoSpec” parameter, the event listener should return an object of this type.

Required permissions

  • webRequest

onResponseStarted

– [Added in TB 45]

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

Parameters for onResponseStarted.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnResponseStartedOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

fromCache

fromCache

(boolean)

Indicates if this response was fetched from disk cache.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

statusCode

statusCode

(integer)

Standard HTTP status code returned by the server.

statusLine

statusLine

(string)

HTTP status line of the response or the ‘HTTP/0.9 200 OK’ string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

ip

[ip]

(string, optional)

The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

The HTTP response headers that were received along with this response.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Required permissions

  • webRequest

onSendHeaders

– [Added in TB 45]

Fired just before a request is going to be sent to the server (modifications of previous onBeforeSendHeaders callbacks are visible by the time onSendHeaders is fired).

Parameters for onSendHeaders.addListener(listener, filter, extraInfoSpec)

listener(details)

listener(details)

A function that will be called when this event occurs.

filter

filter

A set of filters that restricts the events that will be sent to this listener.

extraInfoSpec

[extraInfoSpec]

(array of OnSendHeadersOptions, optional)

Array of extra information that should be passed to the listener function.

Parameters passed to the listener function

details

details

(object)

frameId

frameId

(integer)

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

method

method

(string)

Standard HTTP method.

parentFrameId

parentFrameId

(integer)

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

requestId

requestId

(string)

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

tabId

tabId

(integer)

The ID of the tab in which the request takes place. Set to -1 if the request isn’t related to a tab.

thirdParty

thirdParty

(boolean)

– [Added in TB 72]

Indicates if this request and its content window hierarchy is third party.

timeStamp

timeStamp

(number)

The time when this signal is triggered, in milliseconds since the epoch.

type

type

How the requested resource will be used.

url

url

(string)

cookieStoreId

[cookieStoreId]

(string, optional)

– [Added in TB 68]

The cookie store ID of the contextual identity.

documentUrl

[documentUrl]

(string, optional)

– [Added in TB 54]

URL of the page into which the requested resource will be loaded.

incognito

[incognito]

(boolean, optional)

– [Added in TB 68]

True for private browsing requests.

originUrl

[originUrl]

(string, optional)

– [Added in TB 48]

URL of the resource that triggered this request.

requestHeaders

[requestHeaders]

(HttpHeaders, optional)

The HTTP request headers that have been sent out with this request.

urlClassification

[urlClassification]

(UrlClassification, optional)

– [Added in TB 74]

Tracking classification if the request has been classified.

Note

Classification flags emailtracking and emailtracking_content added in Thunderbird 104.

Required permissions

  • webRequest

Types

BlockingResponse

– [Added in TB 45]

Returns value for event handlers that have the ‘blocking’ extraInfoSpec applied. Allows the event handler to modify network requests.

object

authCredentials

[authCredentials]

(object, optional)

Only used as a response to the onAuthRequired event. If set, the request is made using the supplied credentials.

password

password

(string)

username

username

(string)

cancel

[cancel]

(boolean, optional)

If true, the request is cancelled. Used in onBeforeRequest, this prevents the request from being sent.

redirectUrl

[redirectUrl]

(string, optional)

Only used as a response to the onBeforeRequest and onHeadersReceived events. If set, the original request is prevented from being sent/completed and is instead redirected to the given URL. Redirections to non-HTTP schemes such as data: are allowed. Redirects initiated by a redirect action use the original request method for the redirect, with one exception: If the redirect is initiated at the onHeadersReceived stage, then the redirect will be issued using the GET method.

requestHeaders

[requestHeaders]

(HttpHeaders, optional)

Only used as a response to the onBeforeSendHeaders event. If set, the request is made with these request headers instead.

responseHeaders

[responseHeaders]

(HttpHeaders, optional)

Only used as a response to the onHeadersReceived event. If set, the server is assumed to have responded with these response headers instead. Only return responseHeaders if you really want to modify the headers in order to limit the number of conflicts (only one extension may modify responseHeaders for each request).

upgradeToSecure

[upgradeToSecure]

(boolean, optional)

– [Added in TB 59]

Only used as a response to the onBeforeRequest event. If set, the original request is prevented from being sent/completed and is instead upgraded to a secure request. If any extension returns redirectUrl during onBeforeRequest, upgradeToSecure will have no affect.

CertificateInfo

– [Added in TB 62]

Contains the certificate properties of the request if it is a secure request.

object

fingerprint

fingerprint

(object)

sha1

sha1

(string)

sha256

sha256

(string)

isBuiltInRoot

isBuiltInRoot

(boolean)

issuer

issuer

(string)

serialNumber

serialNumber

(string)

subject

subject

(string)

subjectPublicKeyInfoDigest

subjectPublicKeyInfoDigest

(object)

sha256

sha256

(string)

validity

validity

(object)

Contains start and end timestamps.

end

end

(integer)

start

start

(integer)

rawDER

[rawDER]

(array of integer, optional)

CertificateTransparencyStatus

string

Supported values:

not_applicable

not_applicable

policy_compliant

policy_compliant

policy_not_diverse_scts

policy_not_diverse_scts

policy_not_enough_scts

policy_not_enough_scts

HttpHeaders

– [Added in TB 45]

An array of HTTP headers. Each header is represented as a dictionary containing the keys name and either value or binaryValue.

array of object

OnAuthRequiredOptions

string

Supported values:

asyncBlocking

asyncBlocking

blocking

blocking

responseHeaders

responseHeaders

OnBeforeRedirectOptions

string

Supported values:

responseHeaders

responseHeaders

OnBeforeRequestOptions

string

Supported values:

blocking

blocking

requestBody

requestBody

OnBeforeSendHeadersOptions

string

Supported values:

blocking

blocking

requestHeaders

requestHeaders

OnCompletedOptions

string

Supported values:

responseHeaders

responseHeaders

OnHeadersReceivedOptions

string

Supported values:

blocking

blocking

responseHeaders

responseHeaders

OnResponseStartedOptions

string

Supported values:

responseHeaders

responseHeaders

OnSendHeadersOptions

string

Supported values:

requestHeaders

requestHeaders

RequestFilter

– [Added in TB 45]

An object describing filters to apply to webRequest events.

Note

From Thunderbird 78 onwards, if a filter contains unrecognized values in its types property, then these values are ignored and addListener() proceeds.

Note

Before Thunderbird 78, if a filter contains unrecognized values in its types property, addListener() throws an exception.

object

urls

urls

(array of string)

A list of URLs or URL patterns. Requests that cannot match any of the URLs will be filtered out.

Note

Before Thunderbird 56, moz-extension:// URLs were not allowed.

incognito

[incognito]

(boolean, optional)

If provided, requests that do not match the incognito state will be filtered out.

tabId

[tabId]

(integer, optional)

– [Added in TB 53]

types

[types]

(array of ResourceType, optional)

A list of request types. Requests that cannot match any of the types will be filtered out.

windowId

[windowId]

(integer, optional)

– [Added in TB 53]

ResourceType

– [Added in TB 45]

string

Supported values:

beacon

beacon

csp_report

csp_report

font

font

image

image

imageset

imageset

json

json

– [Added in TB 138]

Note

The “json” property is supported from Thunderbird 135, but requests of this type are only available from Thunderbird 138.

main_frame

main_frame

media

media

object

object

other

other

ping

ping

script

script

speculative

speculative

– [Added in TB 63]

stylesheet

stylesheet

sub_frame

sub_frame

web_manifest

web_manifest

websocket

websocket

xml_dtd

xml_dtd

xmlhttprequest

xmlhttprequest

xslt

xslt

SecurityInfo

– [Added in TB 62]

Contains the security properties of the request (ie. SSL/TLS information).

object

certificates

certificates

(array of CertificateInfo)

Certificate data if state is “secure”. Will only contain one entry unless certificateChain is passed as an option.

state

state

(string)

Supported values:

broken

broken

insecure

insecure

secure

secure

weak

weak

certificateTransparencyStatus

[certificateTransparencyStatus]

Certificate transparency compliance per RFC 6962. See https://www.certificate-transparency.org/what-is-ct for more information.

cipherSuite

[cipherSuite]

(string, optional)

The cipher suite used in this request if state is “secure”.

errorMessage

[errorMessage]

(string, optional)

Error message if state is “broken”

hpkp

[hpkp]

(string, optional)

True if host uses Public Key Pinning and state is “secure”.

hsts

[hsts]

(boolean, optional)

True if host uses Strict Transport Security and state is “secure”.

isDomainMismatch

[isDomainMismatch]

(boolean, optional) Deprecated.

The domain name does not match the certificate domain.

isExtendedValidation

[isExtendedValidation]

(boolean, optional)

isNotValidAtThisTime

[isNotValidAtThisTime]

(boolean, optional) Deprecated.

The certificate is either expired or is not yet valid. See CertificateInfo.validity for start and end dates.

isUntrusted

[isUntrusted]

(boolean, optional) Deprecated.

keaGroupName

[keaGroupName]

(string, optional)

The key exchange algorithm used in this request if state is “secure”.

overridableErrorCategory

[overridableErrorCategory]

(string, optional)

The type of certificate error that was overridden for this connection, if any.

Supported values:

domain_mismatch

domain_mismatch

expired_or_not_yet_valid

expired_or_not_yet_valid

trust_error

trust_error

protocolVersion

[protocolVersion]

(string, optional)

Protocol version if state is “secure”

Supported values:

TLSv1

TLSv1

TLSv1.1

TLSv1.1

TLSv1.2

TLSv1.2

TLSv1.3

TLSv1.3

unknown

unknown

secretKeyLength

[secretKeyLength]

(number, optional)

– [Added in TB 109]

The length (in bits) of the secret key.

signatureSchemeName

[signatureSchemeName]

(string, optional)

The signature scheme used in this request if state is “secure”.

usedDelegatedCredentials

[usedDelegatedCredentials]

(boolean, optional)

– [Added in TB 112]

True if the TLS connection used Delegated Credentials.

usedEch

[usedEch]

(boolean, optional)

– [Added in TB 112]

True if the TLS connection used Encrypted Client Hello.

usedOcsp

[usedOcsp]

(boolean, optional)

– [Added in TB 112]

True if the TLS connection made OCSP requests.

usedPrivateDns

[usedPrivateDns]

(boolean, optional)

– [Added in TB 112]

True if the TLS connection used a privacy-preserving DNS transport like DNS-over-HTTPS.

weaknessReasons

[weaknessReasons]

(array of TransportWeaknessReasons, optional)

list of reasons that cause the request to be considered weak, if state is “weak”

TransportWeaknessReasons

string

Supported values:

cipher

cipher

UploadData

– [Added in TB 45]

Contains data uploaded in a URL request.

object

bytes

[bytes]

(any, optional)

An ArrayBuffer with a copy of the data.

file

[file]

(string, optional)

A string with the file’s path and name.

UrlClassification

object

firstParty

Classification flags if the request has been classified and it is first party.

thirdParty

Classification flags if the request has been classified and it or its window hierarchy is third party.

UrlClassificationFlags

Tracking flags that match our internal tracking classification

string

Supported values:

antifraud

antifraud

any_basic_tracking

any_basic_tracking

any_social_tracking

any_social_tracking

any_strict_tracking

any_strict_tracking

consentmanager

consentmanager

cryptomining

cryptomining

cryptomining_content

cryptomining_content

emailtracking

emailtracking

emailtracking_content

emailtracking_content

fingerprinting

fingerprinting

fingerprinting_content

fingerprinting_content

tracking

tracking

tracking_ad

tracking_ad

tracking_analytics

tracking_analytics

tracking_content

tracking_content

tracking_social

tracking_social

UrlClassificationParty

If the request has been classified this is an array of UrlClassificationFlags.

Properties

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

The maximum number of times that handlerBehaviorChanged can be called per 10 minute sustained interval. handlerBehaviorChanged is an expensive function call that shouldn’t be called often.