Unhook

The Modern Webhook Development Tool for Teams

Unhook is an open-source tool that makes testing webhooks during local development simple and secure. Perfect for teams - share a single webhook endpoint while everyone tests locally.

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.