Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.unhook.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
# 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:
  1. unhook.yml (current directory)
  2. unhook.yaml (current directory)
  3. unhook.config.yml (current directory)
  4. unhook.config.yaml (current directory)
  5. unhook.config.js (current directory)
  6. unhook.config.cjs (current directory)
  7. unhook.config.ts (current directory)
  8. unhook.config.json (current directory)

​
Best Practices

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

​
Troubleshooting

​
Common Issues

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

​
Support