webRequest
Add event listeners for the various stages of making an HTTP request, which includes websocket requests onws:// andwss://. 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 sequence of events is like this:
However, not all of these events might be observed by an extension. For example,onBeforeRedirect might not be followed byonBeforeRequest when the redirect target doesn't match the eventfilter.urls. This can be because the URLs in the filter are narrowly defined, or the redirect target can't be observed by an extension, such as when it redirects to adata: URL.
onErrorOccurred can fire at any time during the request. Also, note that sometimes the sequence of events may differ from this. For example, in Firefox, on anHSTS upgrade, theonBeforeRedirect event is triggered immediately afteronBeforeRequest.onErrorOccurred is also fired ifFirefox Tracking Protection blocks a request.
All events –exceptonErrorOccurred – can take three arguments toaddListener():
- the listener itself
- a
filterobject, so you can only be notified for requests made to particular URLs or for particular types of resource - an optional
extraInfoSpecobject. You can use this to pass additional event-specific instructions.
The listener function is passed adetails 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 thewebRequest API for a given host, an extension must have the"webRequest"API permission and thehost 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 athttps://developer.mozilla.org loads an image fromhttps://mdn.mozillademos.org, then an extension must have both host permissions if it is to intercept the image request.
Modifying requests
On some of these events, you can modify the request. Specifically, you can:
cancel the request in:
redirect the request in:
modify request headers in:
modify response headers in:
supply authentication credentials in:
To do this, you need to pass an option with the value"blocking" in theextraInfoSpec argument to the event'saddListener(). This makes the listener synchronous.
In the listener, you can then return aBlockingResponse object, which indicates the modification you need to make: for example, the modified request header you want to send.
Requests at browser startup
When a listener is registered with the"blocking" option and is registered during the extension startup, if a request is made during the browser startup that matches the listener the extension starts early. This enables the extension to observe the request at browser startup. If you don't take these steps, requests made at startup could be missed.
Speculative requests
The browser can make speculative connections, where it determines that a request to a URI may be coming soon. This type of connection does not provide valid tab information, so request details such astabId,frameId,parentFrameId, etc. are inaccurate. These connections have awebRequest.ResourceType ofspeculative.
Accessing security information
In theonHeadersReceived listener you can access theTLS properties of a request by callinggetSecurityInfo(). To do this you must also pass "blocking" in theextraInfoSpec argument to the event'saddListener().
You can read details of the TLS handshake, but can't modify them or override the browser's trust decisions.
Modifying responses
To modify the HTTP response bodies for a request, callwebRequest.filterResponseData, passing it the ID of the request. This returns awebRequest.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 thehost permission for the relevant host.
Types
webRequest.BlockingResponseAn object of this type is returned by event listeners that have set
"blocking"in theirextraInfoSpecargument. By setting particular properties inBlockingResponse, the listener can modify network requests.webRequest.CertificateInfoAn object describing a single X.509 certificate.
webRequest.HttpHeadersAn array of HTTP headers. Each header is represented as an object with two properties:
nameand eithervalueorbinaryValue.webRequest.RequestFilterAn object describing filters to apply to
webRequestevents.webRequest.ResourceTypeRepresents a particular kind of resource fetched in a web request.
webRequest.SecurityInfoAn object describing the security properties of a particular web request.
webRequest.StreamFilterAn object that can be used to monitor and modify HTTP responses while they are being received.
webRequest.UploadDataContains data uploaded in a URL request.
Properties
webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTESThe maximum number of times that
handlerBehaviorChanged()can be called in a 10 minute period.
Methods
webRequest.handlerBehaviorChanged()This method can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.
webRequest.filterResponseData()Returns a
webRequest.StreamFilterobject for a given request.webRequest.getSecurityInfo()Gets detailed information about theTLS connection associated with a given request.
Events
webRequest.onBeforeRequestFired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.
webRequest.onBeforeSendHeadersFired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.
webRequest.onSendHeadersFired just before sending headers. If your add-on or some other add-on modified headers in
onBeforeSendHeaders, you'll see the modified version here.webRequest.onHeadersReceivedFired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.
webRequest.onAuthRequiredFired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.
webRequest.onResponseStartedFired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirectFired when a server-initiated redirect is about to occur.
webRequest.onCompletedFired when a request is completed.
webRequest.onErrorOccurredFired when an error occurs.
Example extensions
Browser compatibility
Additional notes on Chrome incompatibilities.
Note:This API is based on Chromium'schrome.webRequest API. This documentation is derived fromweb_request.json in the Chromium code.