この記事はまだボランティアによって 日本語 に翻訳されていません。ぜひ MDN に参加して翻訳を手伝ってください!
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 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.
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 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.
To use the webRequest API for a given host, you must have the "webRequest" API permission and the host permission for that host. To use the "blocking" feature you must also have the "webRequestBlocking" API permission.
The webRequest API does not give you access to some security sensitive requests such as update checks and OCSP checks.
Types
webRequest.ResourceType
- Represents a particular kind of resource fetched in a web request.
webRequest.RequestFilter
- An object describing filters to apply to webRequest events.
webRequest.HttpHeaders
- An array of HTTP headers. Each header is represented as an object with two properties:
name
and eithervalue
orbinaryValue
. webRequest.BlockingResponse
-
An object of this type is returned by event listeners that have set
"blocking"
in theirextraInfoSpec
argument. By setting particular properties inBlockingResponse
, the listener can modify network requests. webRequest.UploadData
- Contains data uploaded in a URL request.
Properties
webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
- The maximum number of times that
can be called in a 10 minute period.handlerBehaviorChanged()
Functions
webRequest.handlerBehaviorChanged()
- This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.
Events
webRequest.onBeforeRequest
- 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.
webRequest.onBeforeSendHeaders
- 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.
webRequest.onSendHeaders
- Fired just before sending headers. If your add-on or some other add-on modified headers in
, you'll see the modified version here.onBeforeSendHeaders
webRequest.onHeadersReceived
- Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.
webRequest.onAuthRequired
- Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.
webRequest.onResponseStarted
- 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.
webRequest.onBeforeRedirect
- Fired when a server-initiated redirect is about to occur.
webRequest.onCompleted
- Fired when a request is completed.
webRequest.onErrorOccurred
- Fired when an error occurs.
Browser compatibility
Chrome | Edge | Firefox | Firefox for Android | Opera | |
---|---|---|---|---|---|
BlockingResponse |
Yes | Yes | 45.0 | 48.0 | 33 |
HttpHeaders |
Yes | Yes | 45.0 | 48.0 | 33 |
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES |
Yes | No | 45.0 | 48.0 | 33 |
RequestFilter |
Yes | Yes | 45.0 * | 48.0 * | 33 |
ResourceType |
Yes | Yes | 45.0 | 48.0 | 33 |
UploadData |
Yes | Yes | 45.0 | 48.0 | 33 |
handlerBehaviorChanged |
Yes | Yes | 45.0 | 48.0 | 33 |
onAuthRequired |
Yes | Yes | No | No | 33 |
onBeforeRedirect |
Yes * | Yes | 46.0 * | 48.0 | 33 * |
onBeforeRequest |
Yes * | Yes | 46.0 * | 48.0 * | 33 * |
onBeforeSendHeaders |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
onCompleted |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
onErrorOccurred |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
onHeadersReceived |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
onResponseStarted |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
onSendHeaders |
Yes * | Yes | 45.0 * | 48.0 | 33 * |
The "Chrome incompatibilities" section is included from https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities using the WebExtChromeCompat macro.
If you need to update this content, edit https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities, then shift-refresh this page to see your changes.
Chrome incompatibilities
- Firefox does not support:
onAuthRequired
- filtering by
windowId
andtabId
- the
"requestBody"
instruction inopt_extraInfoSpec
- In Firefox requests can be redirected only if their original URL uses the http or https scheme
Example add-ons
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.
// Copyright 2015 The Chromium Authors. All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.