On some of these events, you can modify the request. Specifically, you can:

• cancel the request in:
  • onBeforeRequest
  • onBeforeSendHeaders
  • onAuthRequired
• redirect the request in:
  • onBeforeRequest
  • onHeadersReceived
• modify request headers in:
  • onBeforeSendHeaders
• modify response headers in:
  • onHeadersReceived
• supply authentication credentials in:
  • onAuthRequired

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.

When a listener is registered with the "blocking" option and is registered during the extension startup, if a request is made during the browser startup that matches the listener the extension starts early. This enables the extension to observe the request at browser startup. If you don't take these steps, requests made at startup could be missed.

The browser can make speculative connections, where it determines that a request to a URI may be coming soon. This type of connection does not provide valid tab information, so request details such as tabId, frameId, parentFrameId, etc. are inaccurate. These connections have a webRequest.ResourceType of speculative.

In the onHeadersReceived listener you can access the TLS properties of a request by calling getSecurityInfo(). 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.

To modify the HTTP response bodies for a request, call webRequest.filterResponseData, passing it the ID of the request. This returns a webRequest.StreamFilter 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

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

An object describing a single X.509 certificate.

webRequest.HttpHeaders

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

webRequest.RequestFilter

An object describing filters to apply to webRequest events.

webRequest.ResourceType

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

webRequest.SecurityInfo

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

webRequest.StreamFilter

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

webRequest.UploadData

Contains data uploaded in a URL request.

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

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

webRequest.handlerBehaviorChanged()

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

Returns a webRequest.StreamFilter object for a given request.

webRequest.getSecurityInfo()

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

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 onBeforeSendHeaders, you'll see the modified version here.

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.

• http-response
• root-cert-stats
• stored-credentials
• user-agent-rewriter