capstan 1.0.0

A webhook inspector for local development

Capstan: The Webhook Inspector

Capstan is a modern, lightweight, and terminal-based webhook inspector for local development. It provides a TUI ( Terminal User Interface) to monitor and inspect incoming HTTP requests, making it the perfect companion for debugging webhooks and API integrations without leaving your terminal.

Features

• Overview: Quick view of method, path, host, and timestamp.
• Headers & Cookies: Complete breakdown of all request headers and cookies.
• Query Parameters: Easy-to-read table of all URL parameters.
• Body Analysis:
  • Syntax Highlighting: Built-in support for JSON, XML, and more.
  • Hexdump: Automatic fallback to a polished hexdump for binary or unknown content.

Capstan is designed to be a simple and lightweight tool. As such, it does not support:

• Persistence: Captured requests are stored in-memory and are lost when the application is closed.
• HTTPS/SSL: The local server only supports HTTP. Use a tunnel like ngrok if you need to receive webhooks from HTTPS sources or from the internet.
• Dynamic Responses: It returns a static response (status, body, headers) for all requests.
• Request Replay: There is no functionality to "replay" or "resend" captured requests.

mitmproxy can be used instead should those advanced features be needed.

Installation

You can install Capstan using uv (recommended) :

uv tool install capstan

Alternatively, you could install it with pipx:

pipx install capstan

Quick Start

Simply run capstan to start the inspector:

capstan

By default, Capstan will start a server on http://127.0.0.1:8080. You can now send requests to this address (or any path under it), and they will appear in the TUI.

You can send then HTTP requests to that address with arbitrary paths. Example:

curl -X POST http://127.0.0.1:8080/test-webhook \
     -H "Content-Type: application/json" \
     -d '{"event": "user_signup", "user_id": 123}'

Usage

See the help documentation for more information:

$ capstan --help
Usage: capstan COMMAND [OPTIONS]

A webhook inspector for local development.

╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help (-h)           Display this message and exit.                         │
│ --install-completion  Install shell completion for this application.         │
│ --version             Display application version.                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ --host    The listen address for the endpoint [default: 127.0.0.1]           │
│ --port    The port for the endpoint [default: 8080]                          │
│ --status  The response status code for the webhook [default: 201]            │
╰──────────────────────────────────────────────────────────────────────────────╯