npm package: @impulselab/reroute
Description: CLI tool to route webhooks to your local development server
Author: Impulse Lab
Latest version: 0.2.0

# 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

```bash
# 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

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

### With Environment Variables

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

### With Custom Machine Name

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

### With Verbose Logging

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

### With Custom Server URL

```bash
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

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

### Testing GitHub Webhooks

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

### Multiple Environments

```bash
# 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

```bash
# 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

```bash
# Watch mode for development
npm run dev
```

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/impulselab/webhook-dispatcher).

## License

MIT