Add event listeners for the various stages of making an HTTP request. 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:

(onErrorOccurred can be fired at any time during the request.)

All the 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 extension to correlate events associated with a single request. It is unique within a browser session and the extension's context. It stays the same throughout a request, even across redirections and authentication exchanges.

The webRequest API does not give you access to some security sensitive requests such as update checks and OCSP checks.


To use the webRequest API for a given host, you must have the "webRequest" API permission. You must also have the host permission for both the host that initiated the request, and the target of the request. For example, if "" loads a resource from "", you must have permission for both those hosts. Note that this is stricter than Chrome, which only requires the host permission for the request's target.

To use the "blocking" feature you must also have the "webRequestBlocking" API permission.

Modifying requests

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.

From Firefox 52 onwards, instead of returning BlockingResponse, the listener can return a Promise which is resolved with a BlockingResponse. This enables the listener to process the request asynchronously.


Represents a particular kind of resource fetched in a web request.
An object describing filters to apply to webRequest events.
An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.

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.

Contains data uploaded in a URL request.


The maximum number of times that handlerBehaviorChanged() can be called in a 10 minute period.


This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.


Fired 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.
Fired 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.
Fired just before sending headers. If your extension or some other extension modified headers in onBeforeSendHeaders, you'll see the modified version here.
Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.
Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.
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.
Fired when a server-initiated redirect is about to occur.
Fired when a request is completed.
Fired when an error occurs.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
BlockingResponse (Yes) (Yes)4548 (Yes)
HttpHeaders (Yes) (Yes)4548 (Yes)
RequestFilter (Yes) (Yes)45 *48 * (Yes)
ResourceType44 * No45 *48 *31 *
UploadData (Yes) (Yes)4548 (Yes)
handlerBehaviorChanged (Yes) (Yes)4548 (Yes)
onAuthRequired (Yes) (Yes)54 *54 * (Yes)
onBeforeRedirect (Yes) * (Yes) *46 *48 (Yes) *
onBeforeRequest (Yes) * (Yes) *46 *48 * (Yes) *
onBeforeSendHeaders (Yes) * (Yes) *45 *48 * (Yes) *
onCompleted (Yes) * (Yes)45 *48 (Yes) *
onErrorOccurred (Yes) * (Yes) *45 *48 (Yes) *
onHeadersReceived (Yes) * (Yes) *45 *48 * (Yes) *
onResponseStarted (Yes) * (Yes) *45 *48 (Yes) *
onSendHeaders (Yes) * (Yes) *45 *48 (Yes) *

Example extensions


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.

Document Tags and Contributors

 Contributors to this page: wbamberg, andrewtruongmoz, abbycar, andymckay
 Last updated by: wbamberg,