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 typical sequence of events is like this:

onErrorOccurred (en-US) can be fired at any time during the request. Also, note that sometimes the sequence of events may differ from this: for example, in Firefox, on an HSTS upgrade, the onBeforeRedirect event will be triggered immediately after onBeforeRequest.

All the events, except onErrorOccurred, can take three arguments to addListener():

  • the listener itself
  • a filter (en-US) 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.

리스너는 요청 정보가 담긴 details 객체를 받는다. 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.

webRequest API를 사용하려면 확장 프로그램은 "webRequest" API 권한을 가져야 하고, 대상 호스트에 대해서도 호스트 권한을 가져야 한다. "blocking" 기능을 사용하려면 추가로 "webRequestBlocking" API 권한도 가져야 한다.

To intercept resources loaded by a page (such as images, scripts, or stylesheets), the extension must have the host permission for the resource as well as for the main page requesting the resource. For example, if a page at "https://developer.mozilla.org" loads an image from "https://mdn.mozillademos.org", then an extension must have both host permissions if it is to intercept the image request.

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 (en-US) object, which indicates the modification you need to make: for example, the modified request header you want to send.

Accessing security information

In the onHeadersReceived (en-US) listener you can access the TLS properties of a request by calling getSecurityInfo() (en-US). To do this you must also pass "blocking" in the extraInfoSpec argument to the event's addListener().

You can read details of the TLS handshake, but can't modify them or override the browser's trust decisions.

Modifying responses

To modify the HTTP response bodies for a request, call webRequest.filterResponseData (en-US), passing it the ID of the request. This returns a webRequest.StreamFilter (en-US) object that you can use to examine and modify the data as it is received by the browser.

To do this, you must have the "webRequestBlocking" API permission as well as the "webRequest" API permission and the host permission for the relevant host.


webRequest.BlockingResponse (en-US)

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.

webRequest.CertificateInfo (en-US)

An object describing a single X.509 certificate.

webRequest.HttpHeaders (en-US)

An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.

webRequest.RequestFilter (en-US)

An object describing filters to apply to webRequest events.

webRequest.ResourceType (en-US)

Represents a particular kind of resource fetched in a web request.

webRequest.SecurityInfo (en-US)

An object describing the security properties of a particular web request.

webRequest.StreamFilter (en-US)

An object that can be used to monitor and modify HTTP responses while they are being received.

webRequest.UploadData (en-US)

Contains data uploaded in a URL request.



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


webRequest.handlerBehaviorChanged() (en-US)

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

webRequest.filterResponseData() (en-US)

Returns a webRequest.StreamFilter (en-US) object for a given request.

webRequest.getSecurityInfo() (en-US)

Gets detailed information about the TLS connection associated with a given request.



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 (en-US)

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 (en-US)

Fired just before sending headers. If your add-on or some other add-on modified headers in onBeforeSendHeaders (en-US), you'll see the modified version here.

webRequest.onHeadersReceived (en-US)

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 (en-US)

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 (en-US)

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 (en-US)

Fired when a server-initiated redirect is about to occur.

webRequest.onCompleted (en-US)

Fired when a request is completed.

webRequest.onErrorOccurred (en-US)

Fired when an error occurs.

브라우저 호환성

BCD tables only load in the browser

Example extensions

참고: AcknowledgmentsThis 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.