Proxy Support

Supported proxy types

Hook supports three proxy protocols:

• HTTP proxy - standard web proxy, used with http:// scheme. For HTTPS targets, Hook opens a CONNECT tunnel through the proxy. For plain HTTP targets, Hook sends requests with an absolute URI.
• HTTPS proxy - TLS-encrypted proxy, used with https:// scheme. Hook connects to the proxy over TLS, then opens a CONNECT tunnel to the target. The proxy connection itself is encrypted.
• SOCKS5 proxy - SOCKS protocol version 5, used with socks5:// scheme. The proxy handles routing transparently for both HTTP and HTTPS targets.

All three proxy types support optional username/password authentication embedded in the proxy URL.

Global proxy configuration

Set the global proxy in the Settings tab or in hook.conf:

proxy_enabled = 1
proxy_url = http://proxy.corp.example.com:3128

The proxy URL format is:

scheme://[user:pass@]host:port

Examples:

http://proxy.corp.example.com:3128
http://alice:s3cret@proxy.corp.example.com:3128
https://secure-proxy.corp.example.com:3129
socks5://socks.corp.example.com:1080
socks5://alice:s3cret@socks.corp.example.com:1080

When proxy_enabled is 0 (default), no proxy is used regardless of the proxy_url value.

Per-request proxy override

Each request has an optional proxy override field in its Settings tab. When set, it overrides the global proxy for that request only.

In the GUI, type the proxy URL into the “Proxy override” field in the request Settings tab.

In collection JSON:

"proxy_override": "http://other-proxy:8080"

When the override field is empty or absent, the global proxy setting applies.

Bypassing the proxy for a specific request

Set the proxy override to the special value direct:// to bypass the proxy entirely for one request, even when a global proxy is enabled.

In collection JSON:

"proxy_override": "direct://"

In the curl export, this produces --noproxy '*'.

The no_proxy list: syntax and matching rules

The no_proxy configuration field is a comma-separated list of hostnames or patterns that should bypass the proxy. Set it in the Settings tab or in hook.conf:

no_proxy = localhost,127.0.0.1,.corp.example.com

Matching rules:

• Exact hostname: proxy.corp matches only proxy.corp.
• Leading dot for subdomains: .example.com matches api.example.com and v2.api.example.com but not example.com.
• Wildcard: * matches everything (bypass proxy for all targets).

Matching is case-insensitive. Whitespace around entries is trimmed.

Proxy authentication: user:pass in the proxy URL

Embed credentials directly in the proxy URL:

http://alice:s3cret@proxy.corp.example.com:3128

For HTTP and HTTPS proxies, this sends a Proxy-Authorization: Basic header with the CONNECT request (HTTPS targets) or with the proxied request (plain HTTP targets).

For SOCKS5 proxies, this uses the SOCKS5 username/password authentication sub-negotiation (RFC 1929).

HTTP proxy with CONNECT tunneling (HTTPS targets)

When the target URL is HTTPS and the proxy is an HTTP proxy, Hook:

1. Opens a TCP connection to the proxy host:port.
2. Sends CONNECT target_host:target_port HTTP/1.1.
3. Includes Proxy-Authorization: Basic ... if credentials are set.
4. Verifies the proxy responds with 200 Connection established.
5. Performs a TLS handshake with the target server over the tunnel.
6. Sends the HTTP request over the TLS connection.

The proxy sees only the CONNECT request. It cannot inspect the encrypted TLS payload.

HTTP proxy with absolute URI (plain HTTP targets)

When the target URL is plain HTTP and the proxy is an HTTP proxy, Hook:

1. Opens a TCP connection to the proxy host:port.
2. Sends the request with an absolute URI in the request line: GET http://target_host:port/path HTTP/1.1.
3. Includes Proxy-Authorization: Basic ... if credentials are set.

The proxy forwards the request to the target server.

HTTPS proxy with CONNECT tunneling

When the proxy scheme is https://, Hook:

1. Opens a TCP connection to the proxy host:port.
2. Performs a TLS handshake with the proxy server.
3. Sends CONNECT target_host:target_port HTTP/1.1 over the encrypted channel.
4. Includes Proxy-Authorization: Basic ... if credentials are set.
5. Verifies the proxy responds with 200 Connection established.
6. Tears down the proxy TLS session, keeping the raw TCP socket.
7. For HTTPS targets, performs a second TLS handshake with the target server.
8. Sends the HTTP request over the connection.

This is useful when the proxy itself requires an encrypted connection (e.g., corporate proxies exposed over the internet).

SOCKS5 proxy

When the proxy scheme is socks5://, Hook:

1. Opens a TCP connection to the proxy host:port.
2. Performs the SOCKS5 handshake (no-auth or user/pass auth).
3. Requests connection to the target host:port via domain name addressing.
4. For HTTPS targets, performs a TLS handshake over the tunnel.
5. Sends the HTTP request normally.

SOCKS5 handles routing transparently. The request line uses a normal relative path, not an absolute URI.

Testing proxy reachability from the GUI

In the Settings tab, the proxy URL is validated when entered. To test proxy connectivity, enable the proxy and send a request. Proxy connection errors appear in the response error message and in the activity log.

Proxy and the curl backend

When the curl subprocess backend is selected (Settings tab checkbox), proxy settings are passed to curl as command-line flags:

• Global or per-request proxy: --proxy <url>
• no_proxy list: --noproxy <list>
• direct:// bypass: --noproxy '*'

curl handles CONNECT tunneling, SOCKS5, and proxy authentication natively.

Proxy and the curl export command

The hook export CLI command includes proxy flags in the generated curl command:

curl -X GET "https://api.example.com/users" --proxy http://proxy:3128 --noproxy localhost,.internal

When proxy_override is direct://:

curl -X GET "https://api.example.com/users" --noproxy '*'

Troubleshooting: common proxy errors and their causes

“Failed to parse proxy URL”

The proxy URL is malformed. Check the format: http://host:port, https://host:port, or socks5://host:port.

“Proxy tunnel connection failed”

Hook connected to the proxy but the CONNECT or SOCKS5 handshake failed. Common causes:

• The proxy rejected the target host:port (firewall rules).
• Proxy authentication is required but no credentials were provided.
• The SOCKS5 proxy does not support the requested auth method.

“TCP connection to proxy failed”

Hook could not reach the proxy server. Check:

• The proxy host and port are correct.
• The proxy server is running and reachable from your network.
• No firewall is blocking the connection.

“TLS handshake via proxy failed”

The TCP tunnel through the proxy was established, but the TLS handshake with the target server failed. This usually means a certificate issue with the target server, not the proxy. See the TLS troubleshooting section in TLS and Certificates.

MITM proxy and custom CAs

If your proxy inspects HTTPS traffic (MITM proxy), it replaces the server certificate with one signed by its own CA. To trust it:

1. Obtain the proxy CA certificate (PEM format).
2. Add it as a custom CA in the Settings tab or hook.conf.
3. TLS verification will pass with the proxy’s replacement certificate.