​
Configuration File

The unhook.yaml file is the primary way to configure Unhook. It supports the following options:

interface WebhookConfig {
  webhookId: string;  // Your unique webhook ID
  debug?: boolean;    // Enable debug mode
  telemetry?: boolean; // Enable telemetry
  destination: Array<{
    name: string;     // Name of the endpoint
    url: string | URL | {  // Local URL to deliver requests to
      protocol?: 'http' | 'https';
      hostname: string;
      port?: string;
      pathname?: string;
      search?: string;
    };
    ping?: boolean | string | URL; // Health check configuration
  }>;
  source?: Array<{
    name: string;     // Name of the source
  }>;
  delivery: Array<{
    source?: string;  // Source of the webhook (defaults to '*')
    destination: string; // Name of the destination to deliver to
  }>;
}

​
Basic Configuration

Here’s a basic configuration example:

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"

​
Advanced Configuration

​
Multiple Destinations

Configure multiple endpoints for different webhook types:

webhookId: "wh_your_webhook_id"
destination:
  - name: "stripe-endpoint"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-endpoint"
    url: "http://localhost:3000/api/webhooks/github"
  - name: "clerk-endpoint"
    url: "http://localhost:3000/api/webhooks/clerk"
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:

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

​
URL Configuration

Configure URLs with different formats:

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

​
Environment Variables

All configuration options can be set via environment variables:

# Core settings
WEBHOOK_ID=wh_your_webhook_id
WEBHOOK_DEBUG=true
WEBHOOK_TELEMETRY=true

# Destination settings
WEBHOOK_DESTINATION_0_NAME=your-endpoint
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=stripe
WEBHOOK_DELIVERY_0_DESTINATION=your-endpoint

​
Team Configuration

​
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"

​
Individual Configuration

Each developer can have their own configuration:

webhookId: "wh_your_webhook_id"
clientId: "dev1"  # Unique client ID
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
source:
  - name: "stripe"
delivery:
  - source: "stripe"
    destination: "local"

​
Security Configuration

​
API Key Authentication

Configure API key authentication for private webhooks:

webhookId: "wh_your_webhook_id"
apiKey: "your_api_key"  # Required for private webhooks
destination:
  - name: "secure-endpoint"
    url: "http://localhost:3000/api/webhooks"

​
Method Restrictions

Restrict allowed HTTP methods:

webhookId: "wh_your_webhook_id"
methods: ["POST", "PUT"]  # Only allow POST and PUT requests
destination:
  - name: "restricted-endpoint"
    url: "http://localhost:3000/api/webhooks"

​
Source Restrictions

Restrict allowed webhook sources:

webhookId: "wh_your_webhook_id"
source:
  - name: "stripe"
    allowed: true
  - name: "github"
    allowed: false

​
Best Practices

  1. Use Meaningful Names: Choose descriptive names for your endpoints
  2. Enable Health Checks: Configure health checks for all endpoints
  3. Use Environment Variables: Store sensitive information in environment variables
  4. Version Control: Keep your configuration in version control
  5. Documentation: Document your configuration for team members

​
Troubleshooting

​
Common Issues

  1. Configuration Loading

    • Check file permissions
    • Verify YAML syntax
    • Ensure required fields are present

  2. URL Configuration

    • Verify URL format
    • Check port availability
    • Test endpoint accessibility

  3. Health Checks

    • Verify health check endpoint
    • Check response format
    • Monitor health check logs

​
Support