You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional enumerated Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters

Google Chrome Extensions (Labs)

WebRequest API

WebRequest API

Use the chrome.experimental.webRequest module to intercept, block, or modify requests in-flight. This module is still very much experimental. For information on how to use experimental APIs, see the chrome.experimental.* APIs page.

Manifest

You must declare the "experimental" permission in the extension manifest to use the webRequest settings API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "experimental"
  ],
  ...
}

Life-cycle of requests

The webRequest API defines the following events:

onBeforeRequest (optionally synchronous)
Fires when a request is about to occur. This is sent before any TCP connection is made and can be used to cancel or redirect requests.
onBeforeSendHeaders (optionally synchronous)
Fires when a request is about to occur and the initial headers are prepared. The event is intended to allow extensions to add, modify and delete request headers (*). The onBeforeSendHeaders event is passed to all subscribers, so different subscribers may attempt to modify the request, see section conflict resolution for details how this is handled. This event can still be used to cancel the request.
onSendHeaders
Fires after all extensions had a chance of modifying the request headers and presents the final (*) version. The event is triggered, before the headers are sent to the network. This event is informational and handled asynchronously. It does not allow to modify or cancel the request.
onResponseStarted
Fires when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available. This event is informational and handled asynchronously. It does not allow to modify or cancel the request.
onBeforeRedirect
Fires before a redirect is about to be executed. A redirection can be triggered by a HTTP response code or by an extension. This event is informational and handled asynchronously. It does not allow to modify or cancel the request.
onCompleted
Fires when a request has been processed successfully.
onErrorOccurred
Fires when a request could not be processed successfully.
The webRequest API gurantees that for each request either onComplete or onErrorOccurred is fired as the final event.

The life-cycle of successful requests can be illustrated as follows:

  |
  v
onBeforeRequest --------------------------------
  |          ^             |                    | [data and file URLs]
  |          |             | [redirection       |
  |           -------      |  from extension]   |
  v                  |     |                    |
onBeforeSendHeaders  |     |                    |
  |     ^            |     |                    |
  v     | [auth]     |     |                    |
onSendHeaders        |     |                    |
  |     |            |     |                    |
  |     v            |     |                    |
  |    onBeforeRedirect <--                     |
  |                                             |
  v                                             |
onResponseStarted <-----------------------------
  |
  v
onCompleted

[auth] = In case of an basic/digest authentication request from server, we send
another HTTP request with the respective headers.
Note that this diagram does not capture a bug that will be fixed soon: If extensions redirect a URL request via the webRequest API, this redirection does not trigger onBeforeRedirect. Instead the request is cancelled and a new request is started at onBeforeRedirect. See http://crbug.com/79520.

(*) Note that the webRequest API presents an abstraction of the network stack to the extension. Internally, one URL request can be split into several HTTP requests (for example to fetch individual byte ranges from a large file) or can be handled by the network stack without communicating with the network. For this reason, the API does not provide the final HTTP headers that are sent to the network. For example all headers that are related to caching are invisible to the extension.

This is a list of headers that are currently not provided to the onBeforeSendHeaders signal. The list is not guaranteed to be complete nor stable:

  • Authorization
  • Cache-Control
  • Connection
  • Content-Length
  • Host
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

Concepts of the webRequest API

The signals of the webRequest API follow certain concepts and patterns that shall be described in the following.

Request IDs

Each request is identified by a request ID. This ID is unique within a browser session and the context of an extension. It remains constant during the the life-cycle of a request and can be used to match signals for the same request.

Subscription

For each signal XXX of the webRequest API, the API provides a function chrome.experimental.webRequest.XXX.addListener() with the following signature.

var callback = function(details) {...};
var opt_filter = {...};
var opt_extraInfoSpec = [...];

chrome.experimental.webRequest.XXX.addListener(
  callback, opt_filter, opt_extraInfoSpec);

Each addListener() call takes a mandatory callback function as the first parameter. This callback function is passed a dictionary containing information about the current URL request. The information in this dictionary depends on the specific event type as well as the content of opt_extraInfoSpec.

If the optional opt_extraInfoSpec array contains the string 'blocking' (only allowed for specific signals), the callback function is handled synchronously. That means that the request is blocked until the callback function returns. In this case, the callback can return a BlockingResponse that determines the further life-cycle of the request. Depending on the context, this response allows cancelling or redirecting a request (onBeforeRequest), or cancelling or modifying headers (onBeforeSendHeaders).

Depending on the specific signal, opt_extraInfoSpec may contain further strings that indicate that specific information shall be passed to the extension. This is used to provide detailed information on requests data only if explicitly requested.

The optional RequestFilter opt_filter allows to limit the requests for which events are triggered in various dimensions:

URLs
URL patterns like *://www.google.com/foo*bar.
Types
Request types like main_frame (a document that is loaded for a top-level frame), sub_frame (a document that is loaded for an embedded frame), image (an image on a web site) and others. See RequestFilter.
Tab IDs
The ID that identifies a specific tab in a window.
Window IDs
The ID that identifies a specific window.

Conflict resolution

In the current implementation of the webRequest API, a request is considered as canceled if at least one extension instructs to cancel the request. If an extension cancels a request, all extensions are notified by an onErrorOccurred event. Only one extension is allowed to redirect a request or modify a header at a time. If more than one extension attempts to modify the request, the most recently installed extension wins while all others are ignored. An extension is currently not notified, if its instruction to modify or redirect has been ignored.

A note about timestamps

It's important to note that some technical oddities in the OS's handling of distinct Chrome processes can cause the clock to be skewed between the browser itself and extension processes. That means that WebRequest's events' timeStamp property is only guaranteed to be internally consistent. Comparing one event to another event will give you the correct offset between them, but comparing them to the current time inside the extension (via (new Date()).getTime(), for instance) might give unexpected results.

Examples

The following example illustrates how to block all requests to www.evil.com:

chrome.experimental.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {},
  ["blocking"]);

The following example achives the same goal in a more efficient way because requests that are not targeted to www.evil.com do not need to be passed to the extension:

chrome.experimental.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {"*://www.evil.com/*"},
  ["blocking"]);

The following example illustrates how the User-Agent header can be deleted from all requests:

chrome.experimental.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    delete details.requestHeaders['User-Agent'];
    return {requestHeaders: details.requestHeaders};
  },
  {},
  ["blocking"]);

Tracking frames

For efficiency reason, the webRequest API does not pass the URL of the frame that issued a request to each request. If this information is required, for example to distinguish between first and third party requests, this example shows how to track the URLs of frames.

// dictionary "windowId" -> "tabId"-"frameId" -> "frameUrl"
var frameUrl = {};

function recordFrameUrl(windowId, tabId, frameId, frameUrl) {
  if (!frameUrl[windowId]) {
    frameUrl[windowId] = {};
  }
  frameUrl[windowId][tabId + "-" + frameId] = frameUrl;
}

function getFrameUrl(windowId, tabId, frameId, frameUrl) {
  return (frameUrl[windowId] || {})[tabId + "-" + frameId];
}

chrome.experimental.webRequest.onBeforeRequest.addListener(
  function(d) {
    if (d.type == 'main_frame' || d.type == 'sub_frame') {
      recordFrameUrl(d.windowId, d.tabId, d.frameId, d.frameUrl);
    }
    var frameUrl = getFrameUrl(d.windowId, d.tabId, d.frameId);
    // Use the frameUrl e.g. to selectively cancel requests.
    // Attention: The frameUrl can be undefined in some cases. Requests may not
    // originate from a frame (e.g. requests from extensions or shared workers).
  });

chrome.windows.onRemoved.addListener(
  function(windowId) {delete frameUrl[windowId];}
  );

API reference: chrome.experimental.webRequest

Methods

Events

onAuthRequired

chrome.experimental.webRequest.onAuthRequired.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired when an authentication failure was received. Depending on whether the user provides credentials, the request is either reissued or cancelled.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
scheme
( Type array of string )
The authentication scheme, e.g. Basic or Digest.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
realm
( optional Type array of string )
The authentication realm provided by the server, if there is one.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
isProxy
( Type array of boolean )
True for Proxy-Authenticate, false for WWW-Authenticate.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the status line and response headers were received, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
responseHeaders
( optional HttpHeaders array of paramType )
The HTTP response headers that were received along with this response.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusLine
( optional Type array of string )
HTTP status line of the response
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["statusLine", "responseHeaders"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

onBeforeRedirect

chrome.experimental.webRequest.onBeforeRedirect.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired when a server initiated redirect is about to occur.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
The URL of the current request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
ip
( optional Type array of string )
The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
fromCache
( Type array of boolean )
Indicates if this response was fetched from disk cache.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusCode
( Type array of integer )
Standard HTTP status code returned by the server.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
redirectUrl
( Type array of string )
The new URL.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the browser was about to make the redirect, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
responseHeaders
( optional HttpHeaders array of paramType )
The HTTP response headers that were received along with this redirect.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusLine
( optional Type array of string )
HTTP status line of the response
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["statusLine", "responseHeaders"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

onBeforeRequest

chrome.experimental.webRequest.onBeforeRequest.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired when a request is about to occur.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
method
( Type array of string )
Standard HTTP method.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
frameId
( Type array of integer )
0 indicates the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
tabId
( Type array of integer )
The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
type
( enumerated Type array of string ["main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", "other"] )
How the requested resource will be used.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the browser was about to make the request, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["blocking"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

paramName
( optional BlockingResponse array of paramType )
If "blocking" is specified in the "extraInfoSpec" parameter, the event listener should return an object of this type.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onBeforeSendHeaders

chrome.experimental.webRequest.onBeforeSendHeaders.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any HTTP data is sent.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the browser was about to send headers, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestHeaders
( optional HttpHeaders array of paramType )
The HTTP request headers that are going to be sent out with this request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["requestLine", "requestHeaders", "blocking"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

paramName
( optional BlockingResponse array of paramType )
If "blocking" is specified in the "extraInfoSpec" parameter, the event listener should return an object of this type.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onCompleted

chrome.experimental.webRequest.onCompleted.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired when a request is completed.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
The URL of the current request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
ip
( optional Type array of string )
The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
fromCache
( Type array of boolean )
Indicates if this response was fetched from disk cache.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusCode
( Type array of integer )
Standard HTTP status code returned by the server.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the response was received completely, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
responseHeaders
( optional HttpHeaders array of paramType )
The HTTP response headers that were received along with this response.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusLine
( optional Type array of string )
HTTP status line of the response
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["statusLine", "responseHeaders"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

onErrorOccurred

chrome.experimental.webRequest.onErrorOccurred.addListener(function(object details) {...}, RequestFilter filter);

Fired when an error occurs.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
The URL of the current request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
ip
( optional Type array of string )
The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
fromCache
( Type array of boolean )
Indicates if this response was fetched from disk cache.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
error
( Type array of string )
The error description. This string is not guaranteed to remain backwards compatible between releases. You must not parse and act based upon its content.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the error occurred, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

onResponseStarted

chrome.experimental.webRequest.onResponseStarted.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

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.

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
ip
( optional Type array of string )
The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
fromCache
( Type array of boolean )
Indicates if this response was fetched from disk cache.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusCode
( Type array of integer )
Standard HTTP status code returned by the server.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the status line and response headers were received, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
responseHeaders
( optional HttpHeaders array of paramType )
The HTTP response headers that were received along with this response.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
statusLine
( optional Type array of string )
HTTP status line of the response
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["statusLine", "responseHeaders"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

onSendHeaders

chrome.experimental.webRequest.onSendHeaders.addListener(function(object details) {...}, RequestFilter filter, array of string extraInfoSpec);

Fired just before a request is going to be sent to the server (modifications of prvious onBeforeSendHeaders callbacks are visible by the time onSendHeaders is fired).

Listener parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestId
( Type array of string )
The ID of the request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
timeStamp
( Type array of number )
The time when the browser finished sending the request, in milliseconds since the epoch.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestHeaders
( optional HttpHeaders array of paramType )
The HTTP request headers that have been sent out with this request.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

filter
( optional RequestFilter array of paramType )
A set of filters that restricts the events that will be sent to this listener.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extraInfoSpec
( optional Type array of Type array of string ["requestLine", "requestHeaders"] paramType )
Array of extra information that should be passed to the listener function.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Listener returns

Types

RequestFilter

paramName
( Type array of object )
An object describing filters to apply to webRequest events.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
urls
( optional Type array of Type array of string paramType )
A list of URLs or URL patterns. Requests that cannot match any of the URLs will be filtered out.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
types
( optional Type array of Type array of string ["main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", "other"] paramType )
A list of request types. Requests that cannot match any of the types will be filtered out.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
tabId
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
windowId
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

HttpHeaders

paramName
( Type array of Type array of object paramType )
An array of HTTP headers, in the form of name/value pairs.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

BlockingResponse

paramName
( Type array of object )
Returns value for event handlers that have the 'blocking' extraInfoSpec applied. Allows the event handler to modify network requests.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
cancel
( optional Type array of boolean )
If true, the request is cancelled. Used in onBeforeRequest, this prevents the request from being sent.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
redirectUrl
( optional Type array of string )
Only used as a response to the onBeforeRequest event. If set, the original request is prevented from being sent and is instead redirected to the given URL.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requestHeaders
( optional HttpHeaders array of paramType )
Only used as a response to the onBeforeSendHeaders event. If set, the request is made with these request headers instead.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.