A CLI for inspecting and replaying captured webhooks from WebhookStash.
Live demo — run one command and watch webhooks arrive instantly:
WebhookStash CLI connects to WebhookStash, a hosted service for capturing and inspecting webhooks in real time. Run one command, get a webhook URL, and see every incoming request directly in your terminal.
For full event history, evidence export, retention policies, and project management, visit webhookstash.com.
Use it for:
- Testing webhooks from Stripe, Shopify, GitHub, or any other provider
- Debugging webhook payloads without setting up tunnels or local servers
- Quickly inspecting headers and request bodies during development
No local server required. WebhookStash is a hosted SaaS that handles webhook ingestion for you.
WebhookStash CLI is a client for inspecting data captured by the hosted WebhookStash service.
It allows you to:
- Stream incoming webhooks in real time
- Inspect request metadata, headers, and bodies
- Replay captured events to your own endpoints
- Export complete webhook evidence as JSON
WebhookStash CLI is NOT:
- A webhook delivery service
- A message queue or broker
- A guaranteed delivery mechanism
- A replacement for your production webhook handler
Webhook delivery, retries, storage, and evidence retention are handled by the hosted WebhookStash service. The CLI is a developer-facing inspection and investigation tool.
go install github.com/farico/webhookstash-cli/cmd/webhookstash@latestThis installs the webhookstash binary to your $GOPATH/bin (or $HOME/go/bin).
git clone https://github.com/farico/webhookstash-cli.git
cd webhookstash-cli
go build -o webhookstash cmd/webhookstash/*.gowebhookstashThis command is interactive and opens your browser on first run.
On first run, the CLI will:
- Open your browser to authenticate via GitHub
- Create a project for you if you don't have one
- Print your webhook ingestion URL and a sample curl command
- Start live tailing incoming webhooks
Example session:
No credentials found. Opening browser to authenticate...
If your browser does not open automatically, visit:
https://webhookstash.com/cli/auth/abc123
Waiting for browser authentication...
✓ Connected to project: quiet-notion-459792
Your webhook ingestion URL: https://api.webhookstash.com/p/proj_abc123/tok_xyz789
Send a test webhook:
curl -X POST -H "Content-Type: application/json" -d '{"hello":"webhookstash"}' https://api.webhookstash.com/p/proj_abc123/tok_xyz789
Starting live tail of incoming webhooks... (Press Ctrl+C to stop)
When webhooks arrive:
────────────────────────────────────────────
POST / • 35 bytes • 2025-01-15 14:32:05.413
Headers:
Content-Type: application/json
User-Agent: curl/8.1.2
Body:
{
"hello": "webhookstash"
}
- Zero configuration — authenticate once and start receiving webhooks immediately
- Automatic project creation — new users get a project with a generated name (e.g.,
quiet-notion-459792) - Live webhook tailing — see incoming requests in real time with pretty-printed JSON
- Multiple projects — switch between projects without re-authenticating
- Auto-reconnection — handles network interruptions gracefully with exponential backoff
- Real-time project sync — responds to project renames and deletions from the web UI
Connect to WebhookStash and start tailing incoming webhooks. Running webhookstash without arguments defaults to webhookstash connect.
webhookstash
webhookstash connect
webhookstash connect --project proj_abc123 --token tok_xyz789| Flag | Description |
|---|---|
--project <id> |
Use a specific project ID (skip interactive selection) |
--token <token> |
Use a project token (requires --project) |
--show-internal-headers |
Show all headers including internal/proxy headers (hidden by default) |
By default, internal headers from proxies and infrastructure (e.g., Via, Timeout-Access, Cf-*) are hidden to reduce noise. Use --show-internal-headers to display everything.
List your configured projects and see which one is the default.
webhookstash projectsYour projects:
● quiet-notion-459792 (default)
ID: proj_abc123
Token: tok_****789
staging-environment
ID: proj_def456
Token: tok_****123
Switch to a different default project for future connect commands.
webhookstash projects switch proj_def456Clear saved credentials and reset to initial state.
webhookstash logoutDisplay detailed information about a captured webhook event, including metadata, request info, headers, and body.
webhookstash event show abc123-def456
webhookstash event show abc123-def456 --json
webhookstash event show abc123-def456 --body full| Flag | Description |
|---|---|
--json |
Output raw JSON response |
--body <mode> |
Body display: preview (default) or full |
Example output:
Event
ID: abc123-def456
Timestamp: 2025-01-15T10:30:00Z
Provider: stripe
Event Type: payment_intent.succeeded
Content-Type: application/json
Body Size: 1234 bytes
Request
Method: POST
Path: /
Source IP: 192.168.1.1
User-Agent: Stripe/1.0
Headers
Content-Type: application/json
Stripe-Signature: t=1234567890,v1=abc123...
Body
{
"id": "evt_xxx",
"type": "payment_intent.succeeded",
...
}
Replay a captured webhook to a target URL. Useful for testing your webhook handler with real data.
webhookstash replay abc123-def456 --to https://example.com/webhook
webhookstash replay abc123-def456 --to http://localhost:3000/api/webhook
webhookstash replay abc123-def456 --to https://example.com/webhook --json| Flag | Description |
|---|---|
--to <url> |
Target URL to replay the webhook to (required) |
--headers-mode <mode> |
Headers to include: all (default), none, or internal |
--json |
Output raw JSON response |
Example output:
Replaying event abc123-def456 to http://localhost:3000/webhook...
Success
Status: 200
Latency: 45ms
Response Preview:
{"status":"ok"}
Download the complete evidence JSON file for an event. Contains all captured data including full body, headers, delivery status, and replay history.
webhookstash evidence abc123-def456 # Output to stdout
webhookstash evidence abc123-def456 --out evidence.json # Save to file
webhookstash evidence abc123-def456 > evidence.json # Pipe to file| Flag | Description |
|---|---|
--out <file> |
Output file path (default: stdout) |
--json |
Same as raw output (for consistency) |
The evidence file is the same format as downloaded from the web UI, suitable for forensics and auditing. Evidence files are immutable snapshots of what WebhookStash received and can be used for audits, incident debugging, or as test fixtures.
The CLI uses a device code flow for secure browser-based authentication:
- CLI requests a device code from the WebhookStash API
- Your browser opens to the GitHub OAuth page
- After authentication, you select or create a project
- The CLI receives project credentials and saves them locally
If the browser doesn't open automatically, the CLI displays a URL to visit manually.
The CLI maintains a WebSocket connection to stream incoming webhooks in real time. Each webhook displays:
- HTTP method and path
- Payload size and timestamp
- Headers (sorted alphabetically)
- Body (JSON is pretty-printed; payloads over 5000 characters are truncated)
If the connection is lost, the CLI automatically reconnects with exponential backoff (1s, 2s, 4s... up to 30s):
⚠️ Lost connection to webhookstash.com. Reconnecting…
Reason: connection timed out
Hint: Check your internet connection, VPN, firewall, or proxy settings.
Retrying in 2s…
Retrying in 4s…
✓ Reconnected to webhookstash.com
Waiting for webhooks...
The CLI responds to server-side changes:
- Project renamed: Updates local config and displays a notification
- Project deleted/archived: Disconnects gracefully with a message
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/webhookstash/config.yaml |
| Linux | ~/.config/webhookstash/config.yaml (or $XDG_CONFIG_HOME/webhookstash/config.yaml) |
| Windows | %APPDATA%\webhookstash\config.yaml |
| Variable | Description |
|---|---|
WEBHOOKSTASH_API_BASE_URL |
Override the API server URL |
WEBHOOKSTASH_BROWSER_AUTH_URL |
Override the browser authentication URL |
These are primarily useful for development or pointing to staging environments.
Do I need to run a local server?
No. WebhookStash is a hosted SaaS. The CLI connects to webhookstash.com and displays webhooks received there.
How do I test webhooks from Stripe, Shopify, etc.?
- Run
webhookstashto get your ingestion URL - Configure the URL in your provider's webhook settings
- Trigger a test event from your provider
- Watch it appear in your terminal
What happens if my credentials become invalid?
The CLI detects authentication failures and prompts you to re-authenticate through the browser.
Can I use this in CI/CD?
You can pass --project and --token flags directly. However, the CLI is primarily designed for interactive development use. The CLI is designed for interactive debugging and inspection, not as a webhook delivery agent in CI pipelines.
go test ./...cmd/webhookstash/
├── main.go # Root command and connect logic
├── main_test.go # Tests for main
├── projects.go # Projects list and switch commands
├── logout.go # Logout command
├── event.go # Event inspection commands
├── replay.go # Replay command
└── evidence.go # Evidence download command
internal/
├── api/ # HTTP API client for event operations
├── auth/ # Browser-based device code authentication
├── config/ # YAML configuration file management
└── websocket/ # WebSocket client with auto-reconnection
- CLI bugs and feature requests: GitHub Issues
- Product feedback and usage questions: GitHub Discussions
- Hosted service and account management: webhookstash.com
MIT