web-request.md

webRequest

Documentation: Chrome WebRequest API

A promise-based wrapper for the Chrome webRequest API, providing methods to observe and modify network requests through various lifecycle events.

Methods

• isAvailableWebRequest()
• handlerWebRequestBehaviorChanged()

Events

• onWebRequestAuthRequired(callback, filter, extraInfoSpec?)
• onWebRequestBeforeRedirect(callback, filter, extraInfoSpec?)
• onWebRequestBeforeRequest(callback, filter, extraInfoSpec?)
• onWebRequestBeforeSendHeaders(callback, filter, extraInfoSpec?)
• onWebRequestSendHeaders(callback, filter, extraInfoSpec?)
• onWebRequestHeadersReceived(callback, filter, extraInfoSpec?)
• onWebRequestResponseStarted(callback, filter, extraInfoSpec?)
• onWebRequestCompleted(callback, filter, extraInfoSpec?)
• onWebRequestErrorOccurred(callback, filter, extraInfoSpec?)

---

isAvailableWebRequest

isAvailableWebRequest(): boolean

Returns true when the webRequest namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. It checks namespace presence only; it does not guarantee individual methods, permissions, or a successful operation.

import {isAvailableWebRequest} from "@addon-core/browser";

if (isAvailableWebRequest()) {
    // The namespace is present; handle operation-specific failures when using it.
}

handlerWebRequestBehaviorChanged

handlerWebRequestBehaviorChanged(): Promise<void>

Notifies the browser that the extension's webRequest handling logic (filters or listeners) has changed, prompting the browser to update its internal event routing.

onWebRequestAuthRequired

onWebRequestAuthRequired(
  callback: (
    details: chrome.webRequest.OnAuthRequiredDetails,
    asyncCallback?: (response: chrome.webRequest.BlockingResponse) => void
  ) => chrome.webRequest.BlockingResponse | void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener for authentication challenges. You can provide credentials, cancel the request, or take no action. Returns a function to remove the listener.

onWebRequestBeforeRedirect

onWebRequestBeforeRedirect(
  callback: (details: chrome.webRequest.OnBeforeRedirectDetails) => void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired before a server-initiated redirect occurs. Returns a function to remove the listener.

onWebRequestBeforeRequest

onWebRequestBeforeRequest(
  callback: (details: chrome.webRequest.OnBeforeRequestDetails) => chrome.webRequest.BlockingResponse | void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired before a request is made. Can cancel or redirect the request by returning a BlockingResponse. Returns a function to remove the listener.

onWebRequestBeforeSendHeaders

onWebRequestBeforeSendHeaders(
  callback: (details: chrome.webRequest.OnBeforeSendHeadersDetails) => chrome.webRequest.BlockingResponse | void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired before HTTP request headers are sent. Can modify or cancel the request headers. Returns a function to remove the listener.

onWebRequestSendHeaders

onWebRequestSendHeaders(
  callback: (details: chrome.webRequest.OnSendHeadersDetails) => void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired after HTTP request headers are sent. Returns a function to remove the listener.

onWebRequestHeadersReceived

onWebRequestHeadersReceived(
  callback: (details: chrome.webRequest.OnHeadersReceivedDetails) => chrome.webRequest.BlockingResponse | void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired when HTTP response headers are received. Can modify response headers or cancel the request. Returns a function to remove the listener.

onWebRequestResponseStarted

onWebRequestResponseStarted(
  callback: (details: chrome.webRequest.OnResponseStartedDetails) => void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired when the first byte of the response body is received. Returns a function to remove the listener.

onWebRequestCompleted

onWebRequestCompleted(
  callback: (details: chrome.webRequest.OnCompletedDetails) => void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired when a request is completed successfully. Returns a function to remove the listener.

onWebRequestErrorOccurred

onWebRequestErrorOccurred(
  callback: (details: chrome.webRequest.OnErrorOccurredDetails) => void,
  filter: chrome.webRequest.RequestFilter,
  extraInfoSpec?: string[]
): () => void

Adds a listener fired when a request encounters an error and is aborted. Returns a function to remove the listener.