Script Hooks Reference

Updated on Nov 11, 2026

A Fiddler Everywhere script is a plain C# script (.csx-style code, without an enclosing class) that defines one or more of the well-known hook methods listed below. Fiddler Everywhere calls the hooks that exist in your active script whenever the corresponding event occurs; hooks you do not define are simply skipped.

Hook methods must be synchronous. Declaring a hook as async or returning Task/Task<T> fails validation.

Available Hooks

HookSignatureTriggered When
OnBeforeRequestvoid OnBeforeRequest(Session oSession)A client request has been received, before it is sent to the server.
OnBeforeResponsevoid OnBeforeResponse(Session oSession)A server response has been received, before it is returned to the client.
OnPeekAtRequestHeadersvoid OnPeekAtRequestHeaders(Session oSession)Request headers are available, before the request body is read.
OnPeekAtResponseHeadersvoid OnPeekAtResponseHeaders(Session oSession)Response headers are available, before the response body is read.
OnSessionCompletedvoid OnSessionCompleted(Session oSession)A session has fully completed.
OnAttachvoid OnAttach()Fiddler Everywhere attaches as the system proxy.
OnDetachvoid OnDetach()Fiddler Everywhere detaches as the system proxy.
OnBootvoid OnBoot()Once, when a script becomes the active script (or when the backend finishes starting up while that script is already active).
OnShutdownvoid OnShutdown()Once, when the Fiddler Everywhere backend begins shutting down.
OnValidateServerCertificatevoid OnValidateServerCertificate(ValidateServerCertificateEventArgs args)A server's HTTPS certificate is evaluated. Set args.ValidityState to override the default validation result (for example, CertificateValidity.ForceValid).
OnWebSocketMessagevoid OnWebSocketMessage(WebSocketMessage oWSM)A WebSocket message is captured.
OnCliCommandCliResult OnCliCommand(string[] parameters)A fiddler-cli command that is not a built-in command is run. parameters[0] is the lowercased command name, and the remaining items are its arguments. Return an CliResult, or null to decline the command. For details, see Custom CLI Commands.
Each hook receives its typed argument (Session, ValidateServerCertificateEventArgs, or WebSocketMessage) directly—there is no need to declare or reference a globals object; the argument name in the signature (oSession, args, oWSM) can be changed freely since it is just a regular method parameter.

A hook receives a copy of its Session, not the live backend object. Changes made during the callback are applied to the real session, but a reference retained after the callback ends will not reflect later session changes, and edits through it will not affect the real session. See Scripting Settings and Limits for details.

Full Sample Script

The following is the built-in template that every new script starts from. It declares every supported hook as an empty stub—delete the hooks you do not need:

csharp
// Fiddler Everywhere sample script.
//
// Security warning: scripts run in a separate process, but are not a hard
// security sandbox. Only run scripts you trust; scripts from untrusted sources
// may access resources available to the script runtime and can contain harmful
// code. A non-cooperating tight loop or deep recursion can hang or crash the
// scripting process.

void OnBeforeRequest(Session oSession)
{
    // Runs when a client request is received, before it is sent to the server.
}

void OnBeforeResponse(Session oSession)
{
    // Runs when a server response is received, before it is returned to the client.
}

void OnPeekAtRequestHeaders(Session oSession)
{
    // Runs as soon as request headers are available (before the body is read).
}

void OnPeekAtResponseHeaders(Session oSession)
{
    // Runs as soon as response headers are available (before the body is read).
}

void OnSessionCompleted(Session oSession)
{
    // Runs after a session has fully completed.
}

void OnAttach()
{
    // Runs when Fiddler attaches as the system proxy.
}

void OnDetach()
{
    // Runs when Fiddler detaches as the system proxy.
}

void OnBoot()
{
    // Runs once when the Fiddler backend finishes starting up.
}

void OnShutdown()
{
    // Runs once when the Fiddler backend begins shutting down.
}

void OnValidateServerCertificate(ValidateServerCertificateEventArgs args)
{
    // Runs when a server's HTTPS certificate is evaluated.
    // Set args.ValidityState to override the default validation result, e.g.:
    // args.ValidityState = CertificateValidity.ForceValid;
}

void OnWebSocketMessage(WebSocketMessage oWSM)
{
    // Runs when a WebSocket message is captured.
}

CliResult OnCliCommand(string[] parameters)
{
    // Runs when a custom command is invoked from a terminal:
    // fiddler-cli <command> [arguments]
    // parameters[0] is the lowercased command; the remaining items are its arguments.
    // Return null to decline a command; the CLI reports it as unknown.
    return null;
}

Autocomplete and Validation

While editing a script, the built-in editor offers:

  • Autocomplete — type . after any expression to see the public members available on its type (for example, oSession. lists the members of Session).
  • Live validation — compile errors and warnings are shown as inline diagnostics (with line/column information) a fraction of a second after you stop typing.

See Also