Requests

HTTP methods

The method dropdown supports: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Select the method before entering the URL.

URL field

The URL field receives keyboard focus automatically when Hook starts, so you can begin typing immediately.

Type the full URL including the scheme (http:// or https://). The URL field supports template expansion: any {{varname}} token is replaced with the value from the active environment before sending.

Example:

{{base_url}}/api/users/{{user_id}}

If no environment is active or the variable is not defined, the token is left as-is.

Query parameters (Params tab)

The Params tab shows a key-value table of query parameters. Each row has a key field, a value field, and an enabled checkbox. Disabled parameters are excluded from the request.

Parameters are appended to the URL as ?key=value&key2=value2. Values support {{varname}} expansion.

Headers tab

The Headers tab shows a key-value table of request headers. Each row has a name, a value, and an enabled checkbox. Disabled headers are not sent.

Header values support {{varname}} expansion.

Body tab

The Body tab has a type selector with six options:

• none: no request body is sent.

• raw: a plain text body. The Content-Type is not set automatically.

• JSON: a JSON body. Content-Type is set to application/json.

• form: form-urlencoded body. Content-Type is set to application/x-www-form-urlencoded.

• multipart: multipart/form-data body for file uploads. Enter one key=value pair per line. Use @filepath for file parts:

  name=My Document
  description=A test file
  file=@/path/to/upload.txt

• GraphQL: a GraphQL query body. Three separate fields appear:

  • Query: the GraphQL query string (required).
  • Variables (JSON): a JSON object of variables (optional).
  • Operation name: the operation to execute (optional).

  The query, variables, and operation name are serialized into a JSON body with keys query, variables, and operationName. Content-Type is set to application/json.

Body content supports {{varname}} expansion.

Auth tab

The Auth tab controls authentication. Six types are available:

• None: no authentication headers are added.
• Bearer: adds an Authorization: Bearer <token> header. One field: Token.
• Basic: adds an Authorization: Basic <base64> header. Two fields: Username, Password.
• API Key: adds the key as a header or query parameter. Three fields: Key name, Key value, and a toggle for “Send as header” (default) or “Send as query parameter”.
• OAuth2 Client Credentials: fetches an access token from a token endpoint and adds it as a Bearer header. Fields: Token URL, Client ID, Client Secret, Scope (optional). The token is cached until it expires.
• Digest: HTTP Digest authentication (RFC 2617). Sends credentials after receiving a 401 challenge. Two fields: Username, Password.

Auth field values support {{varname}} expansion.

Settings tab

The Settings tab contains both per-request and program-wide settings. Per-request defaults are persisted across restarts in hook.conf.

Per-request settings

• Timeout (ms): total request timeout in milliseconds. 0 = no timeout.
• Connect timeout (ms): TCP connection timeout. 0 = no timeout.
• Follow redirects: checkbox. Automatically follow 3xx redirects.
• Max redirects: maximum number of redirects to follow (default 10).
• Retries: number of retries on connection failure or 5xx response.
• Retry delay (ms): delay between retries in milliseconds.
• Request compressed: checkbox. Sends Accept-Encoding: gzip, deflate and auto-decompresses the response body.
• Use curl backend: checkbox. Executes via curl subprocess. The full curl command is logged to the activity log.
• Proxy override: per-request proxy URL, or direct:// to bypass.
• Per-request mTLS: Cert / Key Select and Clear buttons. When set, these override the global client certificate for this request only. The current path is shown next to each button, or (none) if unset. Stored in the request JSON as tls_client_cert / tls_client_key. If both per-request and global are unset, no client certificate is sent. Use Clear to wipe a value imported from a template or collection.

Program-wide settings (also in Settings tab)

• System CA: displays the detected system CA bundle path.
• Custom CA files: listbox of additional PEM CA files, with Add button.
• Skip TLS verification: checkbox. Disables certificate validation.
• Client Certificate (mTLS): Select Cert / Select Key buttons.
• Enable cookie jar: checkbox. Enables domain-aware cookie storage.
• Use custom curl path: checkbox + file selector for curl binary.
• Proxy Settings: Enable proxy, URL, port, user, pass, no_proxy list.

User-Agent presets

Hook includes a User-Agent preset system for quickly switching between browser identities.

Preset files

Presets are JSON files stored in the user-agents/ directory:

{
  "name": "Chrome Windows",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; ...) Chrome/131.0.0.0"
}

Using presets

There are two ways to select a User-Agent:

• Request bar combobox: the UA preset dropdown on the left of the request bar lets you pick a preset for the current request.
• User Agent popup: click “User Agent” in the toolbar to open the full editor. Create new presets, load from file, or save to file.

Selecting a preset sets the User-Agent header on the active request and saves it as the default in hook.conf. The last-used preset is restored on startup.

Sending a request

Click the Send button or press Enter while the URL field has focus to execute the request. The sequence is:

1. Pre-request script runs (if defined).
2. Environment variables are expanded in URL, headers, body, auth.
3. Authentication is applied (headers or params added).
4. The HTTP request is sent via the native backend or curl subprocess.
5. Post-request script runs (if defined).
6. The response is displayed, including a per-phase timing breakdown (see the Times tab below).

Cancelling a request

While a request is in flight, the Send button changes to Cancel. Click it to abort the request – this works with either backend (the native engine’s socket is interrupted; the curl subprocess is killed). The activity log records the cancellation, the status bar shows “Cancelled”, and the button returns to Send. The Timeout (ms) setting also aborts a request automatically once the deadline is reached, on both backends.

Response panel

After a request completes, the response panel shows:

• Status line: HTTP status code + text, elapsed time, body size, header count – all on one line.
• Body tab: the response body, with a Pretty toggle (see below). Gzip/deflate responses are auto-decompressed.
• Headers tab: all response headers as name: value pairs.
• Times tab: a cascading waterfall of the request lifecycle – Prepare, DNS Lookup, TCP Handshake, SSL/TLS, Waiting (TTFB), Download, and Process – each bar offset by the time before it and labelled with its duration. The segments add up to the total. DNS/TCP/SSL show 0 when not applicable (plain HTTP has no SSL). Captured for both backends; the bars rescale to the window width.
• Log tab: the activity log showing request/response events, script output, auth activity, curl commands, network errors.
• Clear button (visible on Log tab): empties the log.
• AutoScroll checkbox (visible on Log tab): auto-scrolls to bottom on new log entries.
• Save button: saves the active tab content (body, headers, or log) to a file via native file dialog. On the Body tab it always saves the raw bytes the server sent, regardless of the Pretty toggle.

Pretty body view

Hook detects the body format from the Content-Type response header (falling back to sniffing the content) and shows a Pretty checkbox with the detected kind (JSON, XML, HTML, JS, YAML) next to the tab buttons when the Body tab is active.

With Pretty checked (the default), the body is shown reformatted and syntax-highlighted:

• JSON is re-indented via the JSON parser.
• XML / HTML are re-indented one tag per line (HTML void elements like <br> and raw <script>/<style> content are handled).
• JavaScript gets a conservative re-indent: minified one-liners are broken at braces and semicolons. Strings, template literals, comments and regex literals (including after return, typeof, case, …) are recognized and copied verbatim, so structural characters inside them never break a line. It is a readability aid, not a full beautifier.
• YAML is highlighted but not reformatted (it is already indented).

Unchecking Pretty shows the raw body exactly as received. The checkbox is disabled when there is nothing to prettify (plain text bodies). Bodies larger than 4 MB are never reformatted. The pretty view is read-only; select text with the mouse and copy it with Ctrl+C.

Response search

The response panel includes a search bar below the tab buttons. To search within the currently active tab (Body, Headers, or Log):

1. Type a search term in the search input field.
2. Click Search (or press Enter) to find the first match.
3. Click Next to jump to the next match, Prev to go back.
4. Click X to clear the search and reset highlighting.

Search is case-insensitive. The matching text is highlighted and the view scrolls to center the match. On the Body tab the search runs in whichever view is visible (pretty or raw). When Next/Prev wraps around past the end or beginning, the statusbar shows a wrap indicator.

Activity log

The Log tab in the response panel shows a timestamped log:

[23:53:33] >> GET https://api.example.com/users
[23:53:33] [auth] applying bearer authentication
[23:53:34] << 200 OK (163 ms, 78.1 KB)
[23:53:34] [script] post-request script executed

Events logged: request send (>>), response received (<<), errors, auth application, script function output (log, get_status, get_header), retry attempts, full curl commands, and network-level errors (DNS resolution failures, TLS handshake errors).

The log is in-memory only, cleared on app restart.

Cookie jar

Hook has a built-in cookie jar that automatically manages cookies across requests, similar to how a browser works.

Enabling the cookie jar

Enable it in the request Settings tab by checking “Enable cookie jar”. You can also set it in hook.conf:

"cookie_jar_enabled": 1,
"cookie_jar_path": "cookies.txt"

How it works

When the cookie jar is enabled:

• Receiving cookies: after each response, Hook parses all Set-Cookie headers and stores the cookies in the jar. Each cookie records its name, value, domain, path, Secure flag, HttpOnly flag, and expiry time.
• Sending cookies: before each request, Hook checks the jar for cookies that match the request domain and path. Matching cookies are sent in a Cookie header automatically.
• Domain matching: cookies are domain-aware. A cookie set for .example.com is sent to api.example.com and www.example.com but not to other.com.
• Secure flag: cookies marked Secure are only sent over HTTPS.

Persistence

The cookie jar is saved to disk in Netscape cookie format (the same format used by curl and browsers). The file path is configured by cookie_jar_path in hook.conf (default: cookies.txt).

The jar is loaded at startup and saved on exit. Session cookies (no expiry) are included in the saved file.

Typical use cases

• Session management: log in once and let the cookie jar carry the session cookie to subsequent requests.
• CSRF tokens: some APIs set a CSRF token cookie that must be sent back. The jar handles this automatically.
• Multi-step API flows: chain requests where later steps depend on cookies set by earlier steps.

Server-Sent Events (SSE)

Hook includes an SSE viewer for streaming event endpoints. SSE is a one-way protocol where the server pushes events to the client over a long-lived HTTP connection.

Using the SSE viewer

1. Click SSE in the toolbar to open the SSE Viewer popup.
2. Enter the SSE endpoint URL (e.g. https://sse.dev/test).
3. Click Connect. The viewer starts receiving events in the background.
4. Received events appear in the event list with their type and data.
5. Click Stop to disconnect.

The SSE viewer runs in a background thread. You can continue using Hook for other requests while the SSE connection is active.

Both HTTP and HTTPS endpoints are supported. The URL scheme determines whether TLS is used.

WebSocket

Hook includes a WebSocket client for interactive bidirectional communication with WebSocket endpoints.

Using the WebSocket popup

1. Click WS in the toolbar to open the WebSocket popup.
2. Enter the WebSocket URL (e.g. wss://echo.websocket.org/). Both ws:// and wss:// (TLS) schemes are supported.
3. Click Connect. The status label updates to show the connected URL.
4. Type a message in the Send field at the bottom and click Send. The message appears in the log with a >> prefix.
5. Incoming messages appear with a << prefix.
6. Click Clear to empty the message log.
7. Click Disconnect to close the connection.

The WS toolbar button turns green while connected.

Message log format

Messages are shown with direction indicators:

>> Hello server
<< {"status":"ok","echo":"Hello server"}
>> ping
<< pong

The receive loop runs in a background thread, so incoming messages appear automatically without blocking the GUI.

curl export

Every request can be exported as a curl command. The curl command reflects all settings:

• Method, URL, headers, body.
• --insecure when TLS verify is off.
• --cacert <path> when a custom CA file is set.
• --cert / --key for client certificates.
• -L --max-redirs for redirect following.
• --compressed for compression.
• --digest --user for digest authentication.
• -A for User-Agent.
• -x <proxy> when a proxy is configured.
• -F for multipart form fields.