Reroute CLI

Route webhooks to your local development server with ease

Reroute CLI is a simple command-line tool that allows you to receive webhooks on your local development server without exposing it to the internet. Perfect for testing webhook integrations during development.

Features

• Simple: One command to start routing webhooks
• Secure: Token-based authentication
• Fast: Long-polling for minimal latency
• Reliable: Automatic reconnection on network issues
• Beautiful: Colorful CLI output with detailed logging

Installation

# Using npx (recommended - no installation required)
npx @impulselab/reroute [webhook-slug] [local-url] --token [token]

# Or install globally
npm install -g @impulselab/reroute

Usage

Basic Usage

npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook --token whk_abc123...

With Environment Variables

# Set token via environment variable
export WEBHOOK_TOKEN=whk_abc123...
npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook

With Custom Machine Name

npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook \
  --token whk_abc123... \
  --name "dev-machine-1"

With Verbose Logging

npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook \
  --token whk_abc123... \
  --verbose

With Custom Server URL

npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook \
  --token whk_abc123... \
  --server https://your-custom-server.com

Options

| Option | Alias | Description | Required | |--------|-------|-------------|----------| | <webhook-slug> | - | The webhook slug to listen to | Yes | | <local-url> | - | The local URL to forward webhooks to | Yes | | --token <token> | -t | Webhook private token (starts with whk_) | Yes* | | --name <name> | -n | Machine name for this connection | No | | --server <url> | -s | Server URL (default: https://webhook-dispatcher.vercel.app) | No | | --verbose | -v | Enable verbose logging | No |

*Token can also be provided via WEBHOOK_TOKEN environment variable

Authentication

Reroute uses token-based authentication for security. Each webhook has a unique private token that starts with whk_.

Getting Your Token

1. Go to your webhook dashboard
2. Create or select a webhook
3. Copy the private token (shown only once during creation)
4. Use it with the --token flag or set it as WEBHOOK_TOKEN environment variable

Token Security

• The token is unique to each webhook
• Keep your token secret (never commit it to version control)
• If compromised, regenerate it from the dashboard
• The token only gives access to the specific webhook, not your entire account

How It Works

1. Registration: The CLI connects to the server and registers a new "localhost" destination
2. Long Polling: The CLI continuously polls the server for new webhooks (60s timeout)
3. Forwarding: When a webhook arrives, it's forwarded to your local URL
4. Response: The CLI sends the local response back to the server for logging

Examples

Testing Stripe Webhooks

npx @impulselab/reroute stripe-webhook http://localhost:3000/api/stripe \
  --token whk_abc123...

Testing GitHub Webhooks

npx @impulselab/reroute github-webhook http://localhost:8000/webhooks/github \
  --token whk_def456...

Multiple Environments

# Development machine
npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook \
  --token whk_abc123... \
  --name "dev-laptop"

# Testing machine
npx @impulselab/reroute my-webhook http://localhost:3000/api/webhook \
  --token whk_abc123... \
  --name "test-server"

Troubleshooting

Connection Issues

If you're having trouble connecting, try:

1. Check your internet connection
2. Verify your token is correct
3. Ensure the webhook slug exists
4. Use --verbose flag for detailed logs

Local Server Not Responding

If your local server isn't responding:

1. Verify the local URL is correct
2. Ensure your local server is running
3. Check firewall settings
4. Test the local URL manually with curl/Postman

Reconnection

The CLI will automatically try to reconnect up to 3 times if the connection is lost. After 3 failed attempts, it will exit. Simply restart the CLI to reconnect.

Development

Building from Source

# Clone the repository
git clone <repo-url>
cd CLI

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
node dist/index.js

Development Mode

# Watch mode for development
npm run dev

Support

For issues, questions, or contributions, please visit the GitHub repository.

License

MIT