webhook-inspector

A production-grade CLI tool for capturing and inspecting incoming webhooks. Point any webhook provider at your local server and see every request pretty-printed in your terminal with full headers, colorized JSON, and an in-memory history.

Built with pure Go. Zero external dependencies. Senior-level code quality with comprehensive test coverage and property-based testing.

✨ Features

🚀 HTTP server with graceful shutdown (SIGINT/SIGTERM/SIGQUIT, 30-second timeout)
🔄 Accepts any HTTP method on a configurable endpoint
🎨 Colorized JSON pretty-printer with automatic NO_COLOR detection
💾 Thread-safe in-memory storage with FIFO eviction
🏥 Health check endpoint with uptime and request count
⚙️ Configuration via CLI flags or environment variables (flags take priority)
🔤 Short flag aliases: -a, -p, -n, -l, -v, -h
📝 Structured logging via log/slog
🏷️ Build metadata injection (version, commit, build time)

📦 Installation

Download pre-built binaries

Binaries are available for Linux, macOS, and Windows on both 64-bit and 32-bit architectures.

🐧 Linux

# 64-bit (amd64)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-linux-amd64 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

# 64-bit (arm64)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-linux-arm64 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

# 32-bit (386)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-linux-386 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

# 32-bit (arm v7)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-linux-arm-v7 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

🍎 macOS

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-darwin-arm64 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

# Intel (amd64)
curl -L https://github.com/DidebanLab/webhook-inspector/releases/latest/download/webhook-inspector-darwin-amd64 -o webhook-inspector
chmod +x webhook-inspector
sudo mv webhook-inspector /usr/local/bin/

🪟 Windows

Download the appropriate binary from the releases page:

64-bit (amd64): webhook-inspector-windows-amd64.exe
64-bit (arm64): webhook-inspector-windows-arm64.exe
32-bit (386): webhook-inspector-windows-386.exe

Add the downloaded executable to your PATH or run it directly from the download location.

🔨 Build from source

Requires Go 1.22 or later.

git clone https://github.com/DidebanLab/webhook-inspector.git
cd webhook-inspector
make build
./bin/webhook-inspector --version

🚀 Usage

Basic usage

webhook-inspector

The server starts on :8088 and listens for webhooks on /webhook.

Custom configuration

webhook-inspector --addr :9090 --path /hooks --max-history 50 --log-level debug

Using short flags

webhook-inspector -a :9090 -p /hooks -n 50 -l debug

Environment variables

export WEBHOOK_ADDR=":9090"
export WEBHOOK_PATH="/hooks"
export WEBHOOK_MAX_HISTORY="200"
export WEBHOOK_LOG_LEVEL="info"
webhook-inspector

CLI flags take priority over environment variables.

Available flags

-a, --addr         <host:port>   Address to listen on            (default: ":8088")
                                  Env: WEBHOOK_ADDR
-p, --path         <path>        URL path to receive webhooks on (default: "/webhook")
                                  Env: WEBHOOK_PATH
-n, --max-history  <1-10000>     Max webhook records in memory   (default: 100)
                                  Env: WEBHOOK_MAX_HISTORY
-l, --log-level    <level>       Log verbosity: debug|info|warn|error
                                                                  (default: "info")
                                  Env: WEBHOOK_LOG_LEVEL
-v, --version                     Print version information and exit
-h, --help                        Show help message and exit

🔌 Endpoints

`POST /webhook` (or your configured path)

Accepts any HTTP method. Stores the request and pretty-prints it to stdout.

Response:

{
  "received": true
}

`GET /health`

Returns server health status, uptime, and total webhook count.

Response:

{
  "status": "ok",
  "uptime": "2h15m30s",
  "webhooks_received": 42
}

🏗️ Architecture

Pure Go implementation with zero external dependencies. The codebase follows production-grade patterns:

Dependency injection - all components are wired in main.go
Interface-based storage - swap in-memory for persistent storage without touching handlers
Structured logging - log/slog with configurable levels
Graceful shutdown - waits up to 30 seconds for in-flight requests
Thread-safe storage - sync.RWMutex protects concurrent access
Property-based testing - validates invariants across all inputs using testing/quick

Project structure

webhook-inspector/
├── cmd/webhook-inspector/   # Entry point, wiring, lifecycle
├── internal/
│   ├── config/              # Flag and env var parsing, validation
│   ├── storage/             # Store interface, in-memory implementation
│   ├── inspector/           # JSON formatter, colorized pretty-printer
│   └── server/              # HTTP server, handlers, graceful shutdown
└── tests/                   # Unit, integration, and property-based tests

🛠️ Development

Prerequisites

Go 1.22 or later
Make (optional, for convenience targets)

Build

make build

Test

make test          # Run all tests
make test-race     # Run tests with race detector

Cross-compile for all platforms

make release-local

Binaries are written to ./dist/ for Linux, macOS, and Windows on amd64, arm64, 386, and arm-v7.

🧪 Testing

The project includes comprehensive test coverage:

Unit tests - concrete inputs with expected outputs
Integration tests - real HTTP requests via httptest.Server
Property-based tests - invariants validated across generated inputs using testing/quick

All tests run with -race detection in CI.

Example property tests

JSON round-trip preservation - parse -> format -> parse produces equivalent values
Storage capacity invariant - list length never exceeds max size, oldest records evicted
UUID uniqueness - all generated IDs are distinct
Concurrent safety - no data races under parallel save/list operations

Run tests:

go test ./tests/...
go test -race ./tests/...

🔄 CI/CD

Continuous Integration

Every push and pull request triggers:

Build verification
Full test suite
Race detector

Automated Releases

Pushing a version tag (e.g. v0.1.0) triggers:

Full test suite with race detection
Cross-platform builds for 9 targets (Linux, macOS, Windows on amd64, arm64, 386, arm-v7)
Automated changelog generation from commit messages
GitHub Release creation with all binaries attached

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome. Please ensure:

All tests pass (make test-race)
Code follows existing patterns (dependency injection, interface-based design)
Commit messages follow conventional format: type(scope): description

💡 Acknowledgments

Built by DidebanLab with a focus on production-grade Go development practices.

Originally created to test webhook integrations for Dideban monitoring services, but designed as a general-purpose tool for developers working with webhooks from any provider.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
cmd/webhook-inspector		cmd/webhook-inspector
internal		internal
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod

Folders and files

Latest commit

History

Repository files navigation