Quickstart

Get started with Unhook in under 5 minutes

Choose Your Setup Method

VS Code Extension

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

1. Install Extension

   1. Open VS Code
   2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
   3. Search for “Unhook - Webhook Development”
   4. Click Install
2. Authenticate

   1. Click the Unhook icon in the Activity Bar
   2. Click “Sign in to Unhook” in the status bar
   3. Complete the OAuth flow in your browser
3. Configure

   Create an unhook.yaml file in your workspace:

   version: 1
   apiKey: your-api-key-here
   delivery:
     destinations:
       - name: local
         url: http://localhost:3000/webhook
         ping: true
   

4. Start Receiving Webhooks

   1. Create a webhook URL at unhook.sh/app
   2. Configure your provider to use the Unhook URL
   3. View events in the VS Code sidebar as they arrive

The VS Code extension provides a complete webhook development environment with real-time monitoring, request replay, and team collaboration features. Learn more →

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

1. Install Extension

   1. Open VS Code
   2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
   3. Search for “Unhook - Webhook Development”
   4. Click Install
2. Authenticate

   1. Click the Unhook icon in the Activity Bar
   2. Click “Sign in to Unhook” in the status bar
   3. Complete the OAuth flow in your browser
3. Configure

   Create an unhook.yaml file in your workspace:

   version: 1
   apiKey: your-api-key-here
   delivery:
     destinations:
       - name: local
         url: http://localhost:3000/webhook
         ping: true
   

4. Start Receiving Webhooks

   1. Create a webhook URL at unhook.sh/app
   2. Configure your provider to use the Unhook URL
   3. View events in the VS Code sidebar as they arrive

The VS Code extension provides a complete webhook development environment with real-time monitoring, request replay, and team collaboration features. Learn more →

1. Installation

   Install Unhook using your preferred package manager:

   # Using npm
   npm install -g @unhook/cli
   
   # Using yarn
   yarn global add @unhook/cli
   
   # Using pnpm
   pnpm add -g @unhook/cli
   
   # Using bun
   bun add -g @unhook/cli
   
   # Using deno
   deno install @unhook/cli
   

2. Initialize Project

   Run the initialization command:

   # Using npx
   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
   

   This will:

   • Open your browser for authentication
   • Create an unhook.yaml file
   • Configure your webhook endpoints
3. Start Your Webhook

   Start the webhook to begin receiving webhooks:

   # Basic usage
   unhook listen
   
   # With custom client ID
   unhook listen --client-id your-name
   
   # With debug logging
   unhook listen --debug
   

4. Configure Your Webhook Provider

   Set up your webhook provider with the provided Unhook URL:

   https://unhook.sh/wh_your_webhook_id
   

Configuration

Basic Configuration

Create an unhook.yaml file in your project root:

webhookId: "wh_your_webhook_id"
debug: false
telemetry: true
destination:
  - name: "your-endpoint"
    url: "http://localhost:3000/api/webhooks"
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "your-endpoint"
  - source: "github"
    destination: "your-endpoint"

Environment Variables

Configure 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

Provider Setup

Stripe

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

https://unhook.sh/wh_your_webhook_id

GitHub

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

https://unhook.sh/wh_your_webhook_id

Clerk

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

https://unhook.sh/wh_your_webhook_id

Team Development

Shared Configuration

Teams can share a single webhook configuration:

webhookId: "wh_team_webhook_id"
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

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

Next Steps

VS Code Extension

Complete webhook development environment in VS Code

Team Setup

Learn how to configure Unhook for your entire team

Dashboard

Monitor and debug your webhooks in real-time

Provider Guides

Detailed setup guides for all supported webhook providers

Support

• Documentation
• GitHub Issues
• Discord Community

Assistant

Responses are generated using AI and may contain mistakes.