Intercept and modify the contents of a request at various stages of its lifetime.
Process: Main
Instances of the WebRequest
class are accessed by using the webRequest
property of a Session
.
The methods of WebRequest
accept an optional filter
and a listener
. The listener
will be called with listener(details)
when the API’s event has happened. The details
object describes the request. Passing null
as listener
will unsubscribe from the event.
The filter
object has a urls
property which is an Array of URL patterns that will be used to filter out the requests that do not match the URL patterns. If the filter
is omitted then all requests will be matched.
For certain events the listener
is passed with a callback
, which should be called with a response
object when listener
has done its work.
An example of adding User-Agent
header for requests:
const {session} = require('electron')
// Modify the user agent for all requests to the following urls.
const filter = {
urls: ['https://*.github.com/*', '*://electron.github.io']
}
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
details.requestHeaders['User-Agent'] = 'MyAgent'
callback({cancel: false, requestHeaders: details.requestHeaders})
})
The following methods are available on instances of WebRequest
:
webRequest.onBeforeRequest([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleuploadData
UploadData[]callback
Function
response
Object
cancel
Boolean (optional)redirectURL
String (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.The listener
will be called with listener(details, callback)
when a request is about to occur.
The uploadData
is an array of UploadData
objects.
The callback
has to be called with an response
object.
webRequest.onBeforeSendHeaders([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
FunctionThe listener
will be called with listener(details, callback)
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.
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
Objectcallback
Function
response
Object
cancel
Boolean (optional)requestHeaders
Object (optional) - When provided, request will be made with these headers.The callback
has to be called with an response
object.
webRequest.onSendHeaders([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublerequestHeaders
ObjectThe listener
will be called with listener(details)
just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders
response are visible by the time this listener is fired.
webRequest.onHeadersReceived([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
FunctionThe listener
will be called with listener(details, callback)
when HTTP response headers of a request have been received.
details
Object
id
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoublestatusLine
StringstatusCode
IntegerresponseHeaders
Objectcallback
Function
response
Object
cancel
BooleanresponseHeaders
Object (optional) - When provided, the server is assumed to have responded with these headers.statusLine
String (optional) - Should be provided when overriding responseHeaders
to change header status otherwise original response header’s status will be used.The callback
has to be called with an response
object.
webRequest.onResponseStarted([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
Boolean - Indicates whether the response was fetched from disk cache.statusCode
IntegerstatusLine
StringThe listener
will be called with listener(details)
when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.
webRequest.onBeforeRedirect([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Stringurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleredirectURL
StringstatusCode
Integerip
String (optional) - The server IP address that the request was actually sent to.fromCache
BooleanresponseHeaders
ObjectThe listener
will be called with listener(details)
when a server initiated redirect is about to occur.
webRequest.onCompleted([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoubleresponseHeaders
ObjectfromCache
BooleanstatusCode
IntegerstatusLine
StringThe listener
will be called with listener(details)
when a request is completed.
webRequest.onErrorOccurred([filter, ]listener)
filter
Object
urls
String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.listener
Function
details
Object
id
Integerurl
Stringmethod
StringresourceType
Stringtimestamp
DoublefromCache
Booleanerror
String - The error description.The listener
will be called with listener(details)
when an error occurs.