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

> Configure Unhook for your development environment

## Configuration File

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

```typescript theme={null}
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:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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)

```yaml theme={null}
# 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

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

### JavaScript/TypeScript

```javascript theme={null}
// 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

* [Documentation](https://docs.unhook.sh)
* [GitHub Issues](https://github.com/unhook-sh/unhook/issues)
* [Discord Community](https://discord.gg/unhook)