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()
:
- the listener itself
- a
filter
object, so you can only be notified for requests made to particular URLs or for particular types of resource - an optional
extraInfoSpec
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.