Unhook

Features

• 🚀 Instant Setup: Get started in seconds with a simple CLI command
• 👥 Team-Friendly: Share one webhook URL across your entire team
• 🔀 Smart Distribution: Automatically routes webhooks to the right developer
• 🔒 Secure by Default: End-to-end encryption for all webhook traffic
• 🌍 Cross-Platform: Works seamlessly on Windows, macOS, and Linux (x64/ARM64)
• 📊 Beautiful Dashboard: Real-time monitoring of webhook requests
• 🔄 Request Replay: Easily replay webhook requests for testing
• 🎯 Smart Routing: Route webhooks to different local ports
• 📝 Request Logging: Detailed logs of all webhook requests
• 🛠️ Built for Developers: Works with popular webhook providers:
  • Stripe
  • GitHub
  • Clerk
  • Discord
  • And many more!

Quick Start

Option 1: VS Code Extension (Recommended)

The fastest way to get started with Unhook is using our VS Code extension:

1. Install Extension

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
   • Search for "Unhook - Webhook Development"
   • Click Install

2. Authenticate

   • Click the Unhook icon in the Activity Bar
   • Click "Sign in to Unhook" in the status bar
   • Complete the OAuth flow in your browser

3. Configure

   • Create an unhook.yml file in your workspace:

webhookUrl: https://unhook.sh/your-org/your-webhook-name destination: - name: local url: http://localhost:3000/api/webhooks delivery: - source: "*" destination: local

4. **Start Receiving Webhooks**
- Create a webhook URL at [unhook.sh/app](https://unhook.sh/app)
- Configure your provider to use the Unhook URL
- View events in the VS Code sidebar as they arrive

### Option 2: CLI

1. **Install CLI**
```bash
# Using npx (recommended)
npx @unhook/cli init

# Using bunx
bunx @unhook/cli init

# Using pnpm
pnpm dlx @unhook/cli init

# Using deno
deno run --allow-net --allow-read --allow-write npm:@unhook/cli init

2. Initialize Project

   npx @unhook/cli init

   This will:

   • Open your browser to authenticate with Unhook
   • Create an unhook.yml file in your project
   • Configure your webhook endpoints

3. Start the Webhook

   npx @unhook/cli listen

   This will create a secure webhook endpoint that delivers requests to your local server based on the configuration.

4. Configure Your Webhook Provider Use the webhook URL in your provider's settings:

   https://unhook.sh/your-org/your-webhook-name

Configuration

Configuration File

The unhook.yml file is the primary way to configure Unhook. It supports the following structure:

# Required: Your unique webhook URL
webhookUrl: https://unhook.sh/your-org/your-webhook-name

# Optional: Enable debug mode
debug: false

# Optional: Enable telemetry
telemetry: true

# Required: Array of destination endpoints
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
    ping: true  # Optional: Health check configuration

# Optional: Array of webhook sources
source:
  - name: stripe
  - name: github

# Required: Array of delivery rules
delivery:
  - source: "*"  # Optional: Source filter (defaults to *)
    destination: local  # Name of the destination from 'destination' array

Environment Variables

All configuration options can be set via environment variables:

# Core settings
WEBHOOK_URL=https://unhook.sh/your-org/your-webhook-name
WEBHOOK_DEBUG=true
WEBHOOK_TELEMETRY=true

# Destination settings
WEBHOOK_DESTINATION_0_NAME=local
WEBHOOK_DESTINATION_0_URL=http://localhost:3000/api/webhooks
WEBHOOK_DESTINATION_0_PING=true

# Source settings
WEBHOOK_SOURCE_0_NAME=stripe
WEBHOOK_SOURCE_1_NAME=github

# Delivery settings
WEBHOOK_DELIVERY_0_SOURCE=*
WEBHOOK_DELIVERY_0_DESTINATION=local

CLI Commands

Core Commands

| Command | Description | |---------|-------------| | unhook init | Authenticate with Unhook and set up your project | | unhook listen | Start the Unhook relay to receive and forward webhooks | | unhook login | Authenticate your CLI with your Unhook account |

Command Options

unhook init

unhook init [options]

Options:
  -c, --code         Authentication code for direct login (advanced)
  -t, --destination  Set the local destination URL to forward webhooks to
  -s, --source       Set the source name for incoming webhooks
  -w, --webhook      Specify a webhook ID to use
  -v, --verbose      Enable verbose debug logging

unhook listen

unhook listen [options]

Options:
  -c, --config       Path to a custom unhook.yml configuration file
  --path             Directory to watch for config changes (default: ".")
  -v, --verbose      Enable verbose debug logging

Team Development

Shared Configuration

Teams can share a single webhook configuration:

webhookUrl: https://unhook.sh/your-org/your-team-webhook
destination:
  - name: dev1
    url: http://localhost:3000/api/webhooks
    ping: true
  - name: dev2
    url: http://localhost:3001/api/webhooks
    ping: true
source:
  - name: clerk
  - name: stripe
delivery:
  - source: clerk
    destination: dev1
  - source: stripe
    destination: dev2

Team Features

• Shared Webhook URL: All team members use the same webhook URL
• Individual Routing: Each developer can receive specific webhook types
• Request History: View and replay requests across the team
• Real-time Monitoring: See incoming requests in real-time
• Team Dashboard: Monitor team activity and webhook status

Cross-Platform Installation

Unhook CLI automatically downloads and installs the correct platform-specific binary for your system during installation. This ensures optimal performance and eliminates the need for compilation or build tools.

Supported Platforms

• Windows: x64 (64-bit)
• macOS: Intel (x64) and Apple Silicon (ARM64)
• Linux: x64 and ARM64 with both glibc and musl (Alpine Linux) support

How It Works

1. Platform Detection: Automatically detects your OS, architecture, and C library variant
2. Binary Download: Downloads the appropriate pre-compiled binary from GitHub releases
3. Smart Caching: Stores binaries locally in ~/.unhook/bin/{version}/ for fast access
4. Transparent Execution: CLI wrapper seamlessly executes the native binary
5. Version Management: Automatically cleans up old versions during updates

Package Manager Support

Works with all major JavaScript package managers:

# npm
npm install -g @unhook/cli

# yarn
yarn global add @unhook/cli

# pnpm
pnpm add -g @unhook/cli

# bun
bun add -g @unhook/cli

For detailed technical information about the cross-platform implementation, see our Cross-Platform CLI Setup Guide.

Provider Setup

Stripe

1. Go to your Stripe Dashboard
2. Click "Add Endpoint"
3. Enter your Unhook URL:

   https://unhook.sh/your-org/your-webhook-name

GitHub

1. Go to your repository settings
2. Navigate to "Webhooks"
3. Click "Add webhook"
4. Enter your Unhook URL:

   https://unhook.sh/your-org/your-webhook-name

Clerk

1. Go to your Clerk Dashboard
2. Navigate to "Webhooks"
3. Click "Add Endpoint"
4. Enter your Unhook URL:

   https://unhook.sh/your-org/your-webhook-name

Security Features

• API key authentication for private webhooks
• Method restrictions
• Source restrictions
• Request body size limits
• Header filtering
• End-to-end encryption

Authentication

Authentication data is stored locally at ~/.unhook/auth-storage.json:

• Authentication state
• User tokens
• Organization ID
• Basic user info

To clear auth data:

rm ~/.unhook/auth-storage.json

Deployment

Unhook can be deployed both as a self-hosted solution or on cloud infrastructure.

Self-Hosted Deployment

Deploy Unhook on your own infrastructure using Docker:

# Quick start
make deploy-local

# Production deployment with nginx
make deploy-prod

Cloud Deployment

Deploy to Kubernetes or cloud providers:

# Deploy to Kubernetes
make deploy-k8s

# Or use cloud-specific deployment guides

For detailed deployment instructions, see our Deployment Guide.

Key Features for Self-Hosting

• Complete Control: Run on your own infrastructure
• Data Privacy: Keep all webhook data within your organization
• Custom Configuration: Adapt to your specific needs
• Docker & Kubernetes: Production-ready deployment options
• High Availability: Built for scale with Redis and PostgreSQL

Documentation

• Quick Start Guide - Get started in under 5 minutes
• CLI Reference - Complete CLI documentation
• VS Code Extension - VS Code extension guide
• Configuration - Configuration file reference
• Provider Guides - Setup guides for webhook providers
• Team Setup - Configure Unhook for your team
• Self-Hosting - Deploy your own Unhook instance

Support

• Documentation
• GitHub Issues
• Discord Community
• Official Website

Contributing

We welcome contributions! See our Contributing Guide for details.

License

Unhook is open source software licensed under the MIT License.