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.

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.

API reference: chrome.experimental.webRequest

Methods

Events

onBeforeRedirect

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

Fires 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.
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));

Fires 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.
tabId
( Type array of integer )
The ID of the tab in which the request takes place. Set to null 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", "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));

Fires 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));

Fires 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.
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));

Fires 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.
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

onRequestSent

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

Fires when a request is sent to the server.

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
( Type array of string )
The server IP address that is actually connected 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.
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

onResponseStarted

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

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.

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.
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

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", "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 )
Return 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. The headers should be delimited by literal "\r\n" substrings.
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.