Package Exports

hooksdash
hooksdash/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hooksdash) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

hooksdash CLI

🚀 Forward webhooks to your local development environment with ease. Perfect for testing webhooks from services like Stripe, GitHub, Twilio, and more—right on your laptop.

Features

Instant Webhook URLs - Get unique webhook URLs for testing without complex setup
Local Forwarding - Forward incoming webhooks to your local development server (localhost)
Real-time Inspection - View request details in the web dashboard in real-time
Replay Functionality - Re-send captured requests to test your handlers
No Port Exposure - Keep your development server private, only accessible via CLI tunnel
Rate Limiting - Built-in rate limiting (60 requests/minute per endpoint)
Multiple Endpoints - Create and manage multiple webhook endpoints
Cross-platform - Works on macOS, Linux, and Windows

Installation

Via npm (Recommended)

npm install -g hooksdash

Via pnpm

pnpm add -g hooksdash

Via yarn

yarn global add hooksdash

Quick Start

1. Create an Endpoint

Visit HooksDash Dashboard and create a new webhook endpoint. You'll get a unique URL like:

https://hooksdash.ibadsiddiqui.dev/api/h/your-unique-slug

2. Authenticate the CLI

hooksdash login

This will open your browser to authenticate. You can also use an API key:

hooksdash login --api-key your_api_key_here

3. Forward to Your Local Server

hooksdash forward --port 3000

This will prompt you to select an endpoint and start forwarding incoming webhooks to http://localhost:3000.

4. Send a Test Webhook

curl -X POST https://hooksdash.ibadsiddiqui.dev/api/h/your-unique-slug \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

You'll see the request forwarded to your local server immediately! 🎉

Commands

`hooksdash login`

Authenticate with HooksDash.

Options:

--api-key <key> - Login with API key (alternative to browser auth)

Examples:

# Browser-based authentication (recommended)
hooksdash login

# API key authentication
hooksdash login --api-key hd_abc123xyz

`hooksdash forward`

Forward incoming webhooks to your local development server.

Options:

--port <port> - Local port to forward to (default: 3000)
--endpoint <slug> - Specific endpoint to forward (optional, will prompt if not provided)

Examples:

# Forward to default port 3000
hooksdash forward

# Forward to specific port
hooksdash forward --port 8000

# Forward to specific endpoint
hooksdash forward --endpoint my-webhook --port 3000

`hooksdash logout`

Logout and remove stored credentials.

hooksdash logout

`hooksdash status`

Check login status and configured endpoints.

hooksdash status

Usage Examples

Stripe Webhooks

Create an endpoint in HooksDash dashboard
Run: hooksdash forward --port 3000
In Stripe Dashboard → Developers → Webhooks, add endpoint:
```
https://hooksdash.ibadsiddiqui.dev/api/h/your-slug
```
Test the webhook - it will forward to your local server!

GitHub Webhooks

Create a repository webhook in GitHub settings

Set the payload URL to your HooksDash endpoint:

https://hooksdash.ibadsiddiqui.dev/api/h/github-webhook

Run: hooksdash forward --endpoint github-webhook --port 3000
Push code - see your webhook events instantly!

Local API Testing

# Terminal 1: Start your local API
npm run dev

# Terminal 2: Forward webhooks
hooksdash forward --port 3000

# Terminal 3: Send test requests
curl -X POST https://hooksdash.ibadsiddiqui.dev/api/h/test-endpoint \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from HooksDash!"}'

Configuration

Environment Variables

Control CLI behavior with environment variables:

# Specify the API endpoint (useful for self-hosted instances)
export HOOKSDASH_API_URL=https://hooksdash.ibadsiddiqui.dev

# Specify the frontend URL
export HOOKSDASH_WEB_URL=https://hooksdash.ibadsiddiqui.dev

# Set default port
export HOOKSDASH_PORT=3000

Config File

Configuration is stored in:

macOS/Linux: ~/.config/hooksdash/config.json
Windows: %APPDATA%\hooksdash\config.json

View your current configuration:

hooksdash status

Troubleshooting

Issue: "Connection refused" when forwarding

Solution: Make sure your local server is running on the specified port:

# Check if port 3000 is in use
netstat -an | grep 3000

# If in use, forward to a different port
hooksdash forward --port 8000

Issue: Webhooks not being received

Solutions:

Verify the endpoint slug matches in your webhook provider
Check CLI is running and shows "Listening for connections"
Ensure your local server is accepting requests on the forwarded port
View real-time requests in the HooksDash dashboard

Solutions:

Clear stored credentials: rm ~/.config/hooksdash/config.json (macOS/Linux) or del %APPDATA%\hooksdash\config.json (Windows)
Try logging in again: hooksdash login
If using API key, verify the key hasn't expired in the dashboard

Issue: CLI crashes or hangs

Solution: Restart the CLI:

# Kill existing process
pkill -f hooksdash

# Start fresh
hooksdash forward

Platform-Specific Notes

macOS

# If installed via Homebrew
brew install hooksdash

# Or via npm
npm install -g hooksdash

# For M1/M2 Macs, ensure Node.js 18+ is installed
node --version

Linux

# Ubuntu/Debian
npm install -g hooksdash

# Fedora/RHEL
npm install -g hooksdash

# For systemd integration, consider running in a tmux/screen session

Windows

# Via npm
npm install -g hooksdash

# Via PowerShell
npm install -global hooksdash

# Or use with WSL (Windows Subsystem for Linux)

Docker

Run the CLI inside Docker:

docker run -it --rm \
  -v ~/.config/hooksdash:/root/.config/hooksdash \
  node:22 \
  npm install -g hooksdash && hooksdash forward --port 3000

API Key Management

Generate a New API Key

Visit HooksDash Dashboard
Go to Settings → API Keys
Click "Generate New Key"
Use with CLI: hooksdash login --api-key your_key_here

Regenerate API Key

# Via dashboard: Settings → API Keys → Regenerate
# Then re-authenticate the CLI
hooksdash logout
hooksdash login

Pricing & Limits

Free Tier

3 webhook endpoints
100 requests per endpoint
24 hour request retention
1 active tunnel

See pricing page for details.

Security

HTTPS Only - All communication is encrypted
Rate Limiting - 60 requests/minute per endpoint
API Key Security - Keys are hashed and never logged
No Data Logging - Request bodies are not stored permanently
Private by Default - Your local server remains private

Support

📖 Full Documentation
📧 Support & issues: ibadsiddiqui01@outlook.com

License

Acknowledgments

Inspired by ngrok and webhook testing best practices
Built with NestJS, Next.js, and Commander.js

Happy webhook testing! 🚀

Made with ❤️ by HooksDash Team

hooksdash