Quickstart

Choose Your Setup Method

VS Code Extension
CLI

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

Install Extension

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

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

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

Start Receiving Webhooks

Create a webhook URL at unhook.sh/app
Configure your provider to use the Unhook URL
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 →

Installation

Install Unhook using your preferred package manager:

# 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

Initialize Project

Run the initialization command:

npx @unhook/cli init

This will:

Open your browser for authentication
Create an unhook.yml file
Configure your webhook endpoints

Start Your Webhook

Start the webhook to begin receiving webhooks:

npx @unhook/cli listen

Configure Your Webhook Provider

Set up your webhook provider with the provided Unhook URL:

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

Configuration

Basic Configuration

Create an unhook.yml file in your project root:

# 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

Configure via environment variables:

# Core settings
WEBHOOK_ID=wh_your_webhook_id
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

Provider Setup

Stripe

Go to your Stripe Dashboard
Click “Add Endpoint”
Enter your Unhook URL:

https://unhook.sh/wh_your_webhook_id

GitHub

Go to your repository settings
Navigate to “Webhooks”
Click “Add webhook”
Enter your Unhook URL:

https://unhook.sh/wh_your_webhook_id

Clerk

Go to your Clerk Dashboard
Navigate to “Webhooks”
Click “Add Endpoint”
Enter your Unhook URL:

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

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

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

Get Started

Reference

Solutions

Development

Choose Your Setup Method

Configuration

Basic Configuration

Environment Variables

Provider Setup

Stripe

GitHub

Clerk

Team Development

Shared Configuration

Team Features

Security Features

Authentication

Next Steps

VS Code Extension

Team Setup

Dashboard

Provider Guides

Support

​Choose Your Setup Method

​Configuration

​Basic Configuration

​Environment Variables

​Provider Setup

​Stripe

​GitHub

​Clerk

​Team Development

​Shared Configuration

​Team Features

​Security Features

​Authentication

​Next Steps

VS Code Extension

Team Setup

Dashboard

Provider Guides

​Support

Choose Your Setup Method

Configuration

Basic Configuration

Environment Variables

Provider Setup

Stripe

GitHub

Clerk

Team Development

Shared Configuration

Team Features

Security Features

Authentication

Next Steps

Support