Add event listeners for the various stages of making an HTTP request, which includes websocket requests on ws://
and wss://
. The event listener receives detailed information about the request and can modify or cancel the request.
Each event is fired at a particular stage of the request. The typical sequence of events is like this:
onErrorOccurred
can be fired at any time during the request. Also, note that sometimes the sequence of events may differ from this: for example, in Firefox, on an HSTS upgrade, the onBeforeRedirect
event will be triggered immediately after onBeforeRequest
.
All events—except onErrorOccurred
—can take three arguments to addListener()
:
filter
object, so you can only be notified for requests made to particular URLs or for particular types of resourceextraInfoSpec
object. You can use this to pass additional event-specific instructions.The listener function is passed a details
object containing information about the request. This includes a request ID, which is provided to enable an add-on to correlate events associated with a single request. It is unique within a browser session and the add-on's context. It stays the same throughout a request, even across redirections and authentication exchanges.
To use the webRequest
API for a given host, an extension must have the "webRequest"
API permission and the host permission for that host. To use the "blocking"
feature, the extension must also have the "webRequestBlocking"
API permission.
To intercept resources loaded by a page (such as images, scripts, or stylesheets), the extension must have the host permission for the resource as well as for the main page requesting the resource. For example, if a page at https://developer.mozilla.org
loads an image from https://mdn.mozillademos.org
, then an extension must have both host permissions if it is to intercept the image request.
On some of these events, you can modify the request. Specifically, you can:
To do this, you need to pass an option with the value "blocking"
in the extraInfoSpec
argument to the event's addListener()
. This makes the listener synchronous.
In the listener, you can then return a BlockingResponse
object, which indicates the modification you need to make: for example, the modified request header you want to send.
In the onHeadersReceived
listener you can access the TLS properties of a request by calling getSecurityInfo()
. To do this you must also pass "blocking" in the extraInfoSpec
argument to the event's addListener()
.
You can read details of the TLS handshake, but can't modify them or override the browser's trust decisions.
To modify the HTTP response bodies for a request, call webRequest.filterResponseData
, passing it the ID of the request. This returns a webRequest.StreamFilter
object that you can use to examine and modify the data as it is received by the browser.
To do this, you must have the "webRequestBlocking"
API permission as well as the "webRequest"
API permission and the host permission for the relevant host.
webRequest.BlockingResponse
An object of this type is returned by event listeners that have set "blocking"
in their extraInfoSpec
argument. By setting particular properties in BlockingResponse
, the listener can modify network requests.
webRequest.CertificateInfo
webRequest.HttpHeaders
name
and either value
or binaryValue
.webRequest.RequestFilter
webRequest
events.webRequest.ResourceType
webRequest.SecurityInfo
webRequest.StreamFilter
webRequest.UploadData
webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
handlerBehaviorChanged()
can be called in a 10 minute period.webRequest.handlerBehaviorChanged()
webRequest.filterResponseData()
webRequest.StreamFilter
object for a given request.webRequest.getSecurityInfo()
webRequest.onBeforeRequest
webRequest.onBeforeSendHeaders
webRequest.onSendHeaders
onBeforeSendHeaders
, you'll see the modified version here.webRequest.onHeadersReceived
webRequest.onAuthRequired
webRequest.onResponseStarted
webRequest.onBeforeRedirect
webRequest.onCompleted
webRequest.onErrorOccurred
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
BlockingResponse |
Yes |
14 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
CertificateInfo |
No |
No |
62 |
? |
No |
No |
? |
? |
62 |
? |
? |
? |
HttpHeaders |
Yes |
14 |
45 |
? |
Yes |
14 |
? |
? |
48 |
? |
? |
? |
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES |
Yes |
14 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
RequestFilter |
Yes
If a filter contains unrecognized values in its
types property, addListener() throws an exception. |
14
If a filter contains unrecognized values in its
types property, addListener() throws an exception. |
45
["From Firefox 78 onwards, if a filter contains unrecognized values in its
types property, then these values are ignored and addListener() proceeds.", "Before Firefox 78, if a filter contains unrecognized values in its types property, addListener() throws an exception."] |
? |
Yes
If a filter contains unrecognized values in its
types property, addListener() throws an exception. |
14 |
? |
? |
48
If a filter contains unrecognized values in its
types property, addListener() throws an exception. |
? |
? |
? |
ResourceType |
44 |
79 |
45 |
? |
31 |
No |
? |
? |
48 |
? |
? |
? |
SecurityInfo |
No |
No |
62 |
? |
No |
No |
? |
? |
62 |
? |
? |
? |
StreamFilter |
No |
No |
57 |
? |
No |
No |
? |
? |
57 |
? |
? |
? |
UploadData |
Yes |
14 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
filterResponseData |
No |
No |
57 |
? |
No |
No |
? |
? |
57 |
? |
? |
? |
getSecurityInfo |
No |
No |
62 |
? |
No |
No |
? |
? |
62 |
? |
? |
? |
handlerBehaviorChanged |
Yes |
14 |
45 |
? |
Yes |
No |
? |
? |
48 |
? |
? |
? |
onAuthRequired |
Yes |
14 |
54
To handle a request asynchronously, return a Promise from the listener.
|
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
54
To handle a request asynchronously, return a Promise from the listener.
|
? |
? |
? |
onBeforeRedirect |
Yes |
14 |
46 |
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
48 |
? |
? |
? |
onBeforeRequest |
Yes
Asynchronous event listeners are not supported.
|
14
Asynchronous event listeners are not supported.
|
46
Asynchronous event listeners are supported from version 52.
|
? |
Yes
Asynchronous event listeners are not supported.
|
14
extraInfoSpec options are not supported.
|
? |
? |
48
Asynchronous event listeners are supported from version 52.
|
? |
? |
? |
onBeforeSendHeaders |
Yes
Asynchronous event listeners are not supported.
|
14
Asynchronous event listeners are not supported.
|
45
Asynchronous event listeners are supported from version 52.
|
? |
Yes
Asynchronous event listeners are not supported.
|
14
extraInfoSpec options are not supported.
|
? |
? |
48
Asynchronous event listeners are supported from version 52.
|
? |
? |
? |
onCompleted |
Yes |
14 |
45 |
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
48 |
? |
? |
? |
onErrorOccurred |
Yes |
14 |
45 |
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
48 |
? |
? |
? |
onHeadersReceived |
Yes
Asynchronous event listeners are not supported.
|
14
Asynchronous event listeners are not supported.
|
45
["Modification of the 'Content-Type' header is supported from version 51.", "Asynchronous event listeners are supported from version 52."]
|
? |
Yes
Asynchronous event listeners are not supported.
|
14
extraInfoSpec options are not supported.
|
? |
? |
48
["Modification of the 'Content-Type' header is supported from version 51.", "Asynchronous event listeners are supported from version 52."]
|
? |
? |
? |
onResponseStarted |
Yes |
14 |
45 |
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
48 |
? |
? |
? |
onSendHeaders |
Yes |
14 |
45 |
? |
Yes |
14
extraInfoSpec options are not supported.
|
? |
? |
48 |
? |
? |
? |
Extra notes on Chrome incompatibilities.
Note: This API is based on Chromium's chrome.webRequest
API. This documentation is derived from web_request.json
in the Chromium code.
Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest