Unhook CLI Tool

The Unhook CLI is a powerful command-line interface that enables developers to test webhooks locally without exposing their development environment to the internet.

Overview

The CLI tool provides a seamless way to:

Create shareable webhook URLs that route to your local environment
Monitor webhook events in real-time
Debug webhook payloads and responses
Collaborate with team members using shared webhook configurations

Installation

Install the Unhook CLI globally using your preferred package manager:

npm install -g @unhook/cli

yarn global add @unhook/cli

pnpm add -g @unhook/cli

bun add -g @unhook/cli

Quick Start

Initialize your project:
npx @unhook/cli init
Start listening for webhooks:
unhook listen --port 3000
Use the generated webhook URL in your provider’s settings:
https://unhook.sh/wh_your_webhook_id

Core Features

Local Webhook Routing

The CLI creates a secure tunnel that routes incoming webhooks to your local development server:

# Route webhooks to local port 3000
unhook listen --port 3000

# Route to a specific endpoint
unhook listen --port 3000 --path /api/webhooks

# Route to a remote URL
unhook listen --redirect https://api.example.com/webhooks

Real-time Monitoring

Monitor webhook activity directly in your terminal:

# Enable debug mode for detailed logging
unhook listen --debug

# View webhook statistics
unhook stats

# Check connection status
unhook status

Team Collaboration

Share webhook URLs across your team while maintaining individual environments:

# Use a shared webhook ID
unhook listen --webhook-id team_webhook_id

# Set a unique client ID for team routing
unhook listen --client-id dev1 --webhook-id team_webhook_id

Configuration

Configuration File

Create an unhook.yaml file in your project root:

webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
debug: false
telemetry: true
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
    ping: true
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "local"
  - source: "github"
    destination: "local"

Environment Variables

All CLI options can be set via environment variables:

# Core settings
WEBHOOK_PORT=3000
WEBHOOK_API_KEY=your_api_key
WEBHOOK_CLIENT_ID=dev-1
WEBHOOK_DEBUG=true

# Advanced settings
WEBHOOK_REDIRECT=https://api.example.com
WEBHOOK_PING=true

Command Reference

`unhook listen`

Start listening for webhook events. Options:

--port, -p: Local port to deliver requests to
--webhook-id, -t: Webhook ID to use
--client-id, -c: Unique client ID for team routing
--redirect, -r: Redirect URL instead of local port
--debug, -d: Enable debug logging
--ping: Health check configuration

Examples:

# Basic usage
unhook listen --port 3000

# With custom client ID
unhook listen --client-id dev-1 --port 3000

# Redirect to remote URL
unhook listen --redirect https://api.example.com/webhooks

`unhook init`

Initialize a new Unhook project. Examples:

# Initialize with default settings
npx @unhook/cli init

# Initialize with specific webhook ID
npx @unhook/cli init --webhook-id wh_123

`unhook status`

Check the status of your webhook connection. Examples:

# Check current status
unhook status

# Check with verbose output
unhook status --verbose

Advanced Features

Health Checks

Configure health checks for your endpoints:

destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
    ping: true  # Enable default health check
  - name: "custom"
    url: "http://localhost:3001/api/webhooks"
    ping: "http://localhost:3001/health"  # Custom health check URL

Multiple Destinations

Route different webhook types to different endpoints:

destination:
  - name: "stripe-endpoint"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-endpoint"
    url: "http://localhost:3000/api/webhooks/github"
delivery:
  - source: "stripe"
    destination: "stripe-endpoint"
  - source: "github"
    destination: "github-endpoint"

Authentication

Configure API key authentication for private webhooks:

webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
apiKey: "your_api_key"  # Required for private webhooks
destination:
  - name: "secure-endpoint"
    url: "http://localhost:3000/api/webhooks"

Integration Examples

Stripe Webhooks

# Start listening for Stripe webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-stripe-webhook

# Configure in Stripe dashboard
# Webhook URL: https://unhook.sh/your-org/your-stripe-webhook

GitHub Webhooks

# Start listening for GitHub webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-github-webhook

# Configure in GitHub repository settings
# Webhook URL: https://unhook.sh/your-org/your-github-webhook

Clerk Authentication

# Start listening for Clerk webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-clerk-webhook

# Configure in Clerk dashboard
# Webhook URL: https://unhook.sh/your-org/your-clerk-webhook

Troubleshooting

Common Issues

Connection Issues

Check your internet connection
Verify the webhook ID is correct
Ensure the port is available and not blocked by firewall

Authentication Problems

Clear auth data: rm ~/.unhook/auth-storage.json
Re-run initialization: npx @unhook/cli init
Verify API key is correct

Webhook Not Receiving Events

Check webhook URL is correctly configured in provider dashboard
Verify webhook is active in Unhook dashboard
Enable debug mode: unhook listen --debug

Debug Mode

Enable debug logging for detailed troubleshooting:

# Enable debug mode
unhook listen --debug

# View debug information in real-time
# Check connection status, webhook events, and error messages

Best Practices

Use Client IDs: Always specify a meaningful client ID in team environments
Enable Health Checks: Configure health checks for all endpoints
Use Configuration Files: Keep settings in version control for team consistency
Monitor Logs: Use debug mode when troubleshooting issues
Secure API Keys: Store sensitive information in environment variables

Next Steps

VS Code Extension - Monitor webhooks in your editor
Team Collaboration - Share webhooks with your team
Provider Integrations - Connect with popular services
Security Features - Learn about data protection

Get Started

Reference

Solutions

Development

CLI Tool

Unhook CLI Tool

Overview

Installation

Quick Start

Core Features

Local Webhook Routing

Real-time Monitoring

Team Collaboration

Configuration

Configuration File

Environment Variables

Command Reference

`unhook listen`

`unhook init`

`unhook status`

Advanced Features

Health Checks

Multiple Destinations

Authentication

Integration Examples

Stripe Webhooks

GitHub Webhooks

Clerk Authentication

Troubleshooting

Common Issues

Debug Mode

Best Practices

Next Steps

​Unhook CLI Tool

​Overview

​Installation

​Quick Start

​Core Features

​Local Webhook Routing

​Real-time Monitoring

​Team Collaboration

​Configuration

​Configuration File

​Environment Variables

​Command Reference

​unhook listen

​unhook init

​unhook status

​Advanced Features

​Health Checks

​Multiple Destinations

​Authentication

​Integration Examples

​Stripe Webhooks

​GitHub Webhooks

​Clerk Authentication

​Troubleshooting

​Common Issues

​Debug Mode

​Best Practices

​Next Steps

Unhook CLI Tool

Overview

Installation

Quick Start

Core Features

Local Webhook Routing

Real-time Monitoring

Team Collaboration

Configuration

Configuration File

Environment Variables

Command Reference

`unhook listen`

`unhook init`

`unhook status`

Advanced Features

Health Checks

Multiple Destinations

Authentication

Integration Examples

Stripe Webhooks

GitHub Webhooks

Clerk Authentication

Troubleshooting

Common Issues

Debug Mode

Best Practices

Next Steps