Configuration

Configuration File

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

interface WebhookConfig {
  webhookUrl: string;  // Required: Your unique webhook URL
  clientId?: string;  // Optional: Unique client identifier
  debug?: boolean;    // Optional: Enable debug mode
  telemetry?: boolean; // Optional: Enable telemetry
  version?: string;   // Optional: Configuration version
  destination: Array<{
    name: string;     // Required: Name of the endpoint
    url: string | URL | RemotePattern;  // Required: Local URL to deliver requests to
    ping?: boolean | string | URL; // Optional: Health check configuration
  }>;
  source?: Array<{
    name: string;     // Required: Name of the source
    secret?: string;  // Optional: Webhook secret for verification
    agent?: HeaderConfig; // Optional: Custom agent header
    timestamp?: HeaderConfig; // Optional: Custom timestamp header
    verification?: HeaderConfig; // Optional: Custom verification header
    defaultTimeout?: number; // Optional: Default timeout in milliseconds
  }>;
  delivery: Array<{
    source?: string;  // Optional: Source of the webhook (defaults to "*")
    destination: string; // Required: Name of the destination to deliver to
  }>;
  server?: {
    apiUrl?: string;  // Optional: Custom API URL for self-hosted instances
    dashboardUrl?: string; // Optional: Custom dashboard URL for self-hosted instances
  };
}

interface RemotePattern {
  protocol?: 'http' | 'https';
  hostname: string;
  port?: string;
  pathname?: string;
  search?: string;
}

interface HeaderConfig {
  key: string;
  type: 'header';
  value: string;
}

Basic Configuration

Here’s a basic configuration example:

# 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

Advanced Configuration

Multiple Destinations

Configure multiple endpoints for different webhook types:

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

Health Checks

Configure health checks for your endpoints:

webhookUrl: https://unhook.sh/your-org/your-webhook-name
destination:
  - name: your-endpoint
    url: http://localhost:3000/api/webhooks
    ping: true  # Enable default health check
  - name: custom-endpoint
    url: http://localhost:3001/api/webhooks
    ping: http://localhost:3001/health  # Custom health check URL
  - name: no-ping-endpoint
    url: http://localhost:3002/api/webhooks
    ping: false  # Disable health checks

URL Configuration

Configure URLs with different formats:

webhookUrl: https://unhook.sh/your-org/your-webhook-name
destination:
  - name: simple-url
    url: http://localhost:3000/api/webhooks
  - name: detailed-url
    url:
      protocol: https
      hostname: localhost
      port: 3000
      pathname: /api/webhooks
      search: ?debug=true
  - name: remote-url
    url: https://api.example.com/webhooks

Source Configuration

Configure webhook sources with advanced options:

webhookUrl: https://unhook.sh/your-org/your-webhook-name
source:
  - name: stripe
    secret: whsec_your_stripe_secret
    defaultTimeout: 30000
  - name: github
    secret: your_github_secret
    agent:
      key: User-Agent
      type: header
      value: GitHub-Hookshot/your-app
    timestamp:
      key: X-GitHub-Timestamp
      type: header
      value: "{{timestamp}}"
  - name: clerk
    verification:
      key: Authorization
      type: header
      value: Bearer {{secret}}
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
delivery:
  - source: "*"
    destination: local

Self-Hosted Configuration

Configure Unhook to work with self-hosted instances:

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

Environment Variables

All configuration options can be set via environment variables:

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

# 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_0_SECRET=whsec_your_secret
WEBHOOK_SOURCE_0_DEFAULT_TIMEOUT=30000

# Delivery settings
WEBHOOK_DELIVERY_0_SOURCE=*
WEBHOOK_DELIVERY_0_DESTINATION=local

# Server settings
WEBHOOK_SERVER_API_URL=https://your-instance.com/api
WEBHOOK_SERVER_DASHBOARD_URL=https://your-instance.com

Team Configuration

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

Individual Configuration

Each developer can have their own configuration:

webhookUrl: https://unhook.sh/your-org/your-webhook-name
clientId: dev1  # Unique client ID
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
source:
  - name: stripe
delivery:
  - source: stripe
    destination: local

Configuration File Formats

Unhook supports multiple configuration file formats:

YAML (Recommended)

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

JSON

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

JavaScript/TypeScript

// unhook.config.js or unhook.config.ts
module.exports = {
  webhookUrl: 'https://unhook.sh/your-org/your-webhook-name',
  destination: [
    {
      name: 'local',
      url: 'http://localhost:3000/api/webhooks'
    }
  ],
  delivery: [
    {
      source: '*',
      destination: 'local'
    }
  ]
};

Configuration File Locations

The CLI and VS Code extension will look for configuration files in the following order:

unhook.yml (current directory)
unhook.yaml (current directory)
unhook.config.yml (current directory)
unhook.config.yaml (current directory)
unhook.config.js (current directory)
unhook.config.cjs (current directory)
unhook.config.ts (current directory)
unhook.config.json (current directory)

Best Practices

Use YAML Format: YAML is the most readable and commonly used format
Use Meaningful Names: Choose descriptive names for your endpoints
Enable Health Checks: Configure health checks for all endpoints
Use Environment Variables: Store sensitive information in environment variables
Version Control: Keep your configuration in version control
Documentation: Document your configuration for team members
Validation: Use the CLI to validate your configuration

Troubleshooting

Common Issues

Configuration Loading
- Check file permissions
- Verify YAML/JSON syntax
- Ensure required fields are present
- Check file location
URL Configuration
- Verify URL format
- Check port availability
- Test endpoint accessibility
- Ensure protocol is specified
Health Checks
- Verify health check endpoint
- Check response format
- Monitor health check logs
- Test endpoint manually
Source Configuration
- Verify source names match delivery rules
- Check secret configuration
- Ensure proper header configuration
- Test webhook verification

Get Started

Reference

Solutions

Development

Configuration File

Basic Configuration

Advanced Configuration

Multiple Destinations

Health Checks

URL Configuration

Source Configuration

Self-Hosted Configuration

Environment Variables

Team Configuration

Shared Configuration

Individual Configuration

Configuration File Formats

YAML (Recommended)

JSON

JavaScript/TypeScript

Configuration File Locations

Best Practices

Troubleshooting

Common Issues

Support

​Configuration File

​Basic Configuration

​Advanced Configuration

​Multiple Destinations

​Health Checks

​URL Configuration

​Source Configuration

​Self-Hosted Configuration

​Environment Variables

​Team Configuration

​Shared Configuration

​Individual Configuration

​Configuration File Formats

​YAML (Recommended)

​JSON

​JavaScript/TypeScript

​Configuration File Locations

​Best Practices

​Troubleshooting

​Common Issues

​Support

Configuration File

Basic Configuration

Advanced Configuration

Multiple Destinations

Health Checks

URL Configuration

Source Configuration

Self-Hosted Configuration

Environment Variables

Team Configuration

Shared Configuration

Individual Configuration

Configuration File Formats

YAML (Recommended)

JSON

JavaScript/TypeScript

Configuration File Locations

Best Practices

Troubleshooting

Common Issues

Support