Skip to content

Extension reference

To build an extension step by step, start with Writing extensions.

request-tools/
extension.json the manifest
request-tools.exe the program for Windows
request-tools the program for macOS
extension.log made by zhttp: what the program wrote to its error output

Extensions go in:

System Folder
Windows %AppData%\zhttp\extensions
macOS ~/Library/Application Support/zhttp/extensions

Settings › Extensions › Open folder opens it. Each extension has its own folder, named after its id. zhttp reads the folders when it starts, and again each time you switch an extension on or off. It empties extension.log each time the extension starts.

Field Needed
id Yes The name of the extension’s folder
name Yes Its name in Settings › Extensions
version No Shown beside the name
description No A line or two under the name, saying what it does
run Yes The program to start, relative to the folder, for windows, macos or linux. One is needed for the system zhttp runs on
viewers No Tabs
commands No Right-click items
hooks No Rules that change traffic
watch No URLs to watch

If zhttp can’t use an extension.json, Settings › Extensions shows why, and the extension doesn’t run.

Each viewer is a tab on the requests or responses it matches, after Raw.

Field
name What the program knows it by. No two viewers can share one
title The tab’s name
on request or response
url The URLs whose requests or responses get the tab

Each command is an item in a request’s right-click menu, under Extensions.

Field
name What the program knows it by. No two commands can share one
title The item’s name

Each hook is a rule the user can add from the Breakpoints panel’s +. It changes the requests or responses the rule matches before they go on.

Field
name What the program knows it by. No two hooks can share one
title The rule’s name in + and in the rule list
on request or response
url The URL a new rule starts with. The user can change it
Field
url zhttp tells the extension about each exchange whose URL this matches, once its response has arrived in full

A pattern matches the whole URL, query string included, ignoring case. * stands for any run of characters.

Pattern Matches
* Every URL
*/api/* Every URL with /api/ in it
https://example.com/* Everything on example.com over HTTPS
*.json URLs that end in .json, with no query string

Add Zhttp.Extensions from NuGet with dotnet add package Zhttp.Extensions. It works with Native AOT.

await new Extension()
.Viewer("base64", async (shown, capture) => View.Plain("…"))
.RunAsync();
Method Handler Runs when
Viewer(name, handler) (Shown, Capture) → Task<View> Someone opens the viewer’s tab, or clicks ↻ in it
Command(name, handler) (Picked, Capture) → Task<CommandResult> Someone picks the command from the right-click menu
Hook(name, handler) (Hooked, Capture) → Task<Message> A request or response matches one of the hook’s rules
Watch(handler) (Watched, Capture) → Task A response arrives in full on a URL in watch
RunAsync() Call it last. It answers zhttp until zhttp stops the extension

Each name matches one in extension.json. zhttp can run several handlers at once, on different threads, so lock anything they share.

Type Properties
Shown Session, Id: the exchange the tab is showing
Picked Session, Ids: the exchanges the user selected
Hooked Session, Id, and Message: the request or response to change
Watched Session, Id, Method, Url, Status

Session is the number of the session the exchange is in. Id names the exchange as "<connection>.<stream>", such as "12.3", the same ID the AI agent tools use.

Handler Returns
Viewer View.Plain(text) for text, or View.Json(json) for JSON. zhttp colours JSON but doesn’t reformat it
Command new CommandResult(Message, Copy). zhttp shows Message as a notice and puts Copy on the clipboard. Either can be left out
Hook The Message zhttp sends on in place of the one it gave you. Change the one you’re given and return it, or return a new one
Watch Nothing

A request or a response.

Member
Method, Url A request’s method and URL
Status A response’s status code
Headers A List<Header> in the order they travelled, without HTTP/2’s pseudo-headers such as :path. new Header(name, value) makes one
Body The body as a byte[], with its Content-Encoding (gzip, br…) removed
Header(name) The value of the first header called name, ignoring case, or null

When a hook returns a message, zhttp compresses the body again as the message’s Content-Encoding header says, and corrects Content-Length. A request needs a method and a URL. A response needs a status from 200 to 599. Header names can’t contain spaces or :, and values can’t contain line breaks.

Every handler gets a Capture as its second argument, for reading and marking the traffic zhttp captured. When a method fails, it throws a ZhttpException with the reason.

Method
GetAsync(session, id) The Exchange: its Request and its Response, with bodies in full. Response is null until it arrives. Fails while a body is still arriving, or when it wasn’t captured in full
FindAsync(session, terms, scopes, before, limit) The exchanges that hold every term, newest first, as ExchangeSummary: Id, Method, Url, Status, MediaType, Started
MarkAsync(session, ids, comment, highlight) Leaves a comment, a highlight or both on exchanges, as the user does

FindAsync looks for the terms in the parts scopes turns on, such as new Scopes(Url: true, ResponseBody: true). The others are RequestHeaders, RequestBody and ResponseHeaders. With no terms, it lists every exchange. before keeps only those that started before that exchange. limit is 1 to 1000, or 0 for 100.

MarkAsync’s highlight is red, orange, yellow, green, blue or purple, or none to take it off. A comment of only spaces takes the comment off. null leaves either as it is.

What Time limit When it fails or runs out of time
Starting 10 seconds Settings › Extensions shows why under its name
A hook 5 seconds The request is dropped, or the response reaches the app as a 502 that says why
A viewer 30 seconds The tab shows the error
A command 30 seconds A notice shows the error
A watcher None The error goes to extension.log
Stopping 2 seconds zhttp ends the program

A rule whose extension is off, removed or not running fails the same way a hook does. See Rules.

The C# library handles the protocol for you. You only need it to write an extension in another language, and Extension examples has one in Go and one in Rust.

zhttp starts the program in its folder and talks to it in JSON-RPC 2.0 over its standard input and output, one message a line in UTF-8. A line carries a whole body, so it can be megabytes long. Read lines without a length limit. Standard output carries messages and nothing else, and standard error goes to extension.log.

Calls go both ways and can overlap. zhttp can send a call before you’ve answered the last one, and you can call zhttp while you handle one. Match each answer to its call by id.

Here is a conversation, where → is zhttp writing to the program and ← is the program writing to zhttp:

→ {"jsonrpc":"2.0","id":1,"method":"hello","params":{"protocol":1}}
← {"jsonrpc":"2.0","id":1,"result":{}}
→ {"jsonrpc":"2.0","id":2,"method":"command","params":{"command":"copy-urls","session":1,"ids":["7.1"]}}
← {"jsonrpc":"2.0","id":1,"method":"get","params":{"session":1,"id":"7.1"}}
→ {"jsonrpc":"2.0","id":1,"result":{"request":{"method":"GET","url":"https://api.example.com/a","headers":[["accept","*/*"]],"body":""},"response":{"status":200,"headers":[["content-type","application/json"]],"body":"eyJvayI6dHJ1ZX0="}}}
← {"jsonrpc":"2.0","id":2,"result":{"message":"Copied 1 URLs","copy":"https://api.example.com/a\n"}}
→ {"jsonrpc":"2.0","method":"shutdown","params":{}}

A request or a response is:

{ "method": "POST", "url": "https://api.example.com/a", "headers": [["content-type", "application/json"]], "body": "eyJvayI6dHJ1ZX0=" }

headers are [name, value] pairs in the order they travelled, without HTTP/2’s pseudo-headers. body is base64, with its Content-Encoding removed. A request has method and url. A response has status instead.

Method Params Answer with
hello { "protocol": 1 } {}. zhttp sends it first
view { "viewer", "session", "id" } { "format", "text" }, where format is "text" or "json"
command { "command", "session", "ids" } { "message", "copy" }. Both are optional
hook { "hook", "session", "id", "message" } { "message" }: the message to send on
watched { "session", "id", "method", "url", "status" } Nothing. It’s a notification, with no id
shutdown {} Nothing. Exit within 2 seconds

To refuse a call, answer with a JSON-RPC error. zhttp shows its message to the user.

Method Params zhttp answers
get { "session", "id" } { "request", "response" }. response is null until it arrives
find { "session", "terms", "scopes", "before", "limit" } { "exchanges": [{ "id", "method", "url", "status", "media_type", "started" }] }, newest first
mark { "session", "ids", "comment", "highlight" } {}

scopes is an object with any of url, request_headers, request_body, response_headers and response_body set to true. before, limit, comment and highlight can be left out, and work as in Capture.