# Create Plant
Source: https://docs.unhook.sh/api-reference/endpoint/create

POST /plants



# Delete Plant
Source: https://docs.unhook.sh/api-reference/endpoint/delete

DELETE /plants/{id}



# Get Plants
Source: https://docs.unhook.sh/api-reference/endpoint/get

GET /plants



# New Plant
Source: https://docs.unhook.sh/api-reference/endpoint/webhook

WEBHOOK /plant/webhook



# Introduction
Source: https://docs.unhook.sh/api-reference/introduction

Example section for showcasing API endpoints

<Note>
  If you're not looking to build API reference documentation, you can delete
  this section by removing the api-reference folder.
</Note>

## Welcome

There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.

<Card title="Plant Store Endpoints" icon="leaf" href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json">
  View the OpenAPI specification file
</Card>

## Authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

```json theme={null}
"security": [
  {
    "bearerAuth": []
  }
]
```


# MCP Integration Examples
Source: https://docs.unhook.sh/api-reference/mcp/examples

Common workflows and usage patterns for the MCP server

# MCP Integration Examples

Learn how to use the Unhook MCP server effectively with these practical examples and workflows.

## Common Debugging Workflows

### Investigating Failed Webhooks

When webhooks start failing, use this workflow to identify and resolve issues:

<CodeGroup>
  ```typescript Claude Desktop theme={null}
  // 1. Ask Claude to investigate failures
  "Show me all failed webhook events from the last hour"

  // Claude will use search_events tool:
  {
    "name": "search_events",
    "arguments": {
      "status": "failed",
      "limit": 100
    }
  }

  // 2. Analyze specific failure
  "Why did event evt_123 fail?"

  // Claude will use analyze_event tool:
  {
    "name": "analyze_event", 
    "arguments": {
      "eventId": "evt_123"
    }
  }

  // 3. Get recommendations
  "What should I do to fix these webhook failures?"
  ```

  ```typescript Cursor theme={null}
  // In Cursor Composer, type:
  // "Debug why my Stripe webhooks are failing"

  // Cursor will automatically:
  // 1. Search for failed Stripe events
  // 2. Analyze error patterns
  // 3. Suggest fixes in your code
  ```
</CodeGroup>

### Performance Monitoring

Track webhook performance and identify bottlenecks:

```typescript theme={null}
// Ask: "Generate a performance report for my webhooks"

// The AI will use get_webhook_stats:
{
  "name": "get_webhook_stats",
  "arguments": {
    "timeRange": "24h"
  }
}

// Follow up with:
// "Which webhook has the slowest response time?"
// "Show me the performance trend over the last week"
```

### Payload Inspection

Examine webhook payloads for debugging:

```typescript theme={null}
// Ask: "Show me the payload for the last GitHub webhook"

// The AI will:
// 1. Read recent events
// 2. Filter for GitHub provider
// 3. Show the payload data

// Or be specific:
// "What data did Stripe send in event evt_xyz?"
```

## Advanced Use Cases

### Failure Pattern Analysis

Identify recurring issues across webhooks:

```typescript theme={null}
// Ask: "Find patterns in webhook failures over the last 7 days"

// The AI will:
{
  "name": "get_webhook_stats",
  "arguments": {
    "timeRange": "7d"
  }
}

// Then analyze error distribution and suggest:
// - Common failure causes
// - Time-based patterns
// - Affected endpoints
```

### Comparative Analysis

Compare webhook performance:

```typescript theme={null}
// Ask: "Compare success rates between my Stripe and PayPal webhooks"

// The AI will gather stats for both:
[
  {
    "name": "get_webhook_stats",
    "arguments": {
      "webhookId": "wh_stripe_prod",
      "timeRange": "24h"
    }
  },
  {
    "name": "get_webhook_stats",
    "arguments": {
      "webhookId": "wh_paypal_prod",
      "timeRange": "24h"
    }
  }
]
```

### Event Replay Preparation

Prepare to replay failed events:

```typescript theme={null}
// Ask: "Help me replay the failed payment webhooks from today"

// The AI will:
// 1. Search for failed payment events
// 2. Analyze why they failed
// 3. Suggest fixes before replay
// 4. Provide replay instructions
```

## Integration Patterns

### Continuous Monitoring

Set up regular health checks:

```typescript theme={null}
// Morning routine:
"Give me a webhook health summary for the last 24 hours"

// The AI provides:
// - Total events processed
// - Success/failure rates
// - Any new error types
// - Performance metrics
// - Recommendations
```

### Incident Response

Quick debugging during outages:

```typescript theme={null}
// When alerts fire:
"URGENT: Webhooks are failing. What's happening?"

// Rapid diagnosis flow:
// 1. Check recent failures
// 2. Identify error patterns  
// 3. Analyze specific failures
// 4. Provide immediate fixes
```

### Development Testing

Validate webhook implementations:

```typescript theme={null}
// During development:
"Show me the test webhooks I sent in the last hour"

// Verify payloads:
"Is my endpoint receiving the correct Stripe signature?"

// Debug issues:
"Why is my local endpoint returning 401?"
```

## Prompt Engineering Tips

### Effective Queries

<Tabs>
  <Tab title="Good Prompts">
    ```
    ✓ "Show me failed Stripe webhooks from the last hour"
    ✓ "Why did event evt_123 fail?"
    ✓ "Compare webhook performance this week vs last week"
    ✓ "What's causing timeout errors on my GitHub webhook?"
    ```
  </Tab>

  <Tab title="Better Prompts">
    ```
    ✓ "Analyze all payment webhook failures from today and suggest fixes"
    ✓ "Create a performance report comparing all my webhooks"
    ✓ "Debug evt_123 and show me similar failures"
    ✓ "Find patterns in webhook failures and recommend preventive measures"
    ```
  </Tab>
</Tabs>

### Context Building

Provide context for better analysis:

```typescript theme={null}
// Instead of: "Why are webhooks failing?"
// Try: "My Stripe webhooks started failing after deploying v2.1. 
//       Show me what changed and how to fix it."

// Instead of: "Show webhook stats"  
// Try: "Generate a performance report for customer-facing webhooks,
//       focusing on payment processing delays"
```

## Automation Ideas

### Daily Reports

```typescript theme={null}
// Morning standup prep:
"Generate a daily webhook report with:
- Total events processed
- Failure rate by provider
- New error types since yesterday
- Performance degradation warnings
- Top 3 issues to address"
```

### Alert Investigation

```typescript theme={null}
// When monitoring alerts trigger:
"Investigate webhook alert: 
- Error rate above 5% for wh_stripe_prod
- Started 15 minutes ago
- Show me what's failing and why"
```

### Pre-deployment Checks

```typescript theme={null}
// Before deploying:
"Analyze webhook health for the last 2 hours.
Are there any issues I should fix before deploying?"
```

## Code Integration Examples

### Error Handler Improvement

```typescript theme={null}
// Ask: "Based on recent failures, how should I improve my webhook error handling?"

// The AI analyzes failures and suggests:
class WebhookHandler {
  async processWebhook(payload: any) {
    try {
      // Validate signature
      if (!this.validateSignature(payload)) {
        // AI notices many 401 errors
        throw new UnauthorizedError('Invalid signature');
      }
      
      // Process with timeout
      // AI suggests timeout based on performance stats
      const result = await Promise.race([
        this.process(payload),
        this.timeout(30000) // 30s based on p99 latency
      ]);
      
      return result;
    } catch (error) {
      // AI suggests specific error handling
      if (error.code === 'ECONNREFUSED') {
        // Retry logic for connection issues
        return this.scheduleRetry(payload);
      }
      throw error;
    }
  }
}
```

### Monitoring Integration

```typescript theme={null}
// Ask: "Generate monitoring code based on common webhook issues"

// The AI creates:
class WebhookMonitor {
  async checkHealth() {
    // Based on MCP data analysis
    const stats = await this.getWebhookStats('24h');
    
    // Alert on high failure rate
    if (stats.failureRate > 0.05) {
      await this.alert('High failure rate', stats);
    }
    
    // Alert on performance degradation
    if (stats.p95Latency > 5000) {
      await this.alert('Slow webhook processing', stats);
    }
  }
}
```

## Best Practices

### 1. Start Broad, Then Narrow

```typescript theme={null}
// First: "Show me webhook health overview"
// Then: "Focus on failed Stripe payment webhooks"  
// Finally: "Analyze event evt_123 in detail"
```

### 2. Use Time Ranges Effectively

```typescript theme={null}
// Recent issues: "last hour", "last 24h"
// Trends: "last 7d", "last 30d"
// Comparisons: "this week vs last week"
```

### 3. Combine Multiple Tools

```typescript theme={null}
// Don't just search, also analyze:
"Find failed webhooks AND explain why they failed AND suggest fixes"
```

### 4. Ask for Actionable Insights

```typescript theme={null}
// Instead of: "Show me errors"
// Ask: "What specific changes should I make to reduce webhook failures?"
```

## Troubleshooting Examples

### No Data Appearing

```typescript theme={null}
// Diagnose: "Why am I not seeing any webhook data?"
// The AI will check:
// - If webhooks are configured
// - If events are being received
// - If there are permission issues
```

### Inconsistent Results

```typescript theme={null}
// Ask: "Why do some webhooks work but others fail randomly?"
// The AI analyzes:
// - Success patterns
// - Failure patterns
// - Environmental factors
// - Suggests targeted fixes
```

## Next Steps

* Review the [Tools Reference](/api-reference/mcp/tools) for detailed parameters
* Check the [Resources Reference](/api-reference/mcp/resources) for data schemas
* See the [MCP Overview](/api-reference/mcp/overview) for protocol details
* Read the [Integration Guide](/mcp-integration) for setup instructions


# MCP API Overview
Source: https://docs.unhook.sh/api-reference/mcp/overview

Model Context Protocol API endpoints and specifications

# MCP API Overview

The Unhook MCP (Model Context Protocol) server provides a standardized interface for AI assistants to access webhook data and debugging tools.

## Base URL

```
https://app.unhook.sh/api/mcp
```

## Authentication

All requests require authentication using a Bearer token:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from [https://unhook.sh/app/api-keys](https://unhook.sh/app/api-keys).

## Transport

The MCP server supports HTTP Server-Sent Events (SSE) transport for real-time bidirectional communication.

## Protocol

The server implements the Model Context Protocol v1.0 specification with JSON-RPC 2.0 messages.

### Request Format

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "resources/list",
  "params": {}
}
```

### Response Format

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "resources": [...]
  }
}
```

## Available Methods

### Resources

<ResponseField name="resources/list" type="method">
  Lists all available resources

  **Response:**

  ```json theme={null}
  {
    "resources": [
      {
        "uri": "webhook://events/recent",
        "name": "Recent Webhook Events",
        "description": "Last 100 webhook events"
      },
      {
        "uri": "webhook://requests/recent",
        "name": "Recent Webhook Requests",
        "description": "Last 100 webhook requests"
      },
      {
        "uri": "webhook://webhooks/list",
        "name": "Webhook List",
        "description": "All configured webhooks"
      }
    ]
  }
  ```
</ResponseField>

<ResponseField name="resources/read" type="method">
  Reads a specific resource

  **Parameters:**

  * `uri` (string, required): Resource URI to read

  **Example Request:**

  ```json theme={null}
  {
    "method": "resources/read",
    "params": {
      "uri": "webhook://events/recent"
    }
  }
  ```
</ResponseField>

### Tools

<ResponseField name="tools/list" type="method">
  Lists all available tools

  **Response includes:**

  * `search_events` - Search webhook events
  * `search_requests` - Search webhook requests
  * `analyze_event` - Analyze specific event
  * `analyze_request` - Analyze specific request
  * `get_webhook_stats` - Get webhook statistics
</ResponseField>

<ResponseField name="tools/call" type="method">
  Executes a tool with parameters

  **Parameters:**

  * `name` (string, required): Tool name
  * `arguments` (object, required): Tool-specific arguments

  **Example Request:**

  ```json theme={null}
  {
    "method": "tools/call",
    "params": {
      "name": "search_events",
      "arguments": {
        "webhookId": "wh_123",
        "status": "failed",
        "limit": 50
      }
    }
  }
  ```
</ResponseField>

### Prompts

<ResponseField name="prompts/list" type="method">
  Lists all available prompts

  **Response includes:**

  * `debug_webhook_issue` - Debugging workflow
  * `analyze_failures` - Failure analysis
  * `performance_report` - Performance analysis
</ResponseField>

<ResponseField name="prompts/get" type="method">
  Gets a specific prompt template

  **Parameters:**

  * `name` (string, required): Prompt name

  **Response:**

  ```json theme={null}
  {
    "name": "debug_webhook_issue",
    "description": "Help debug webhook issues",
    "arguments": [
      {
        "name": "webhookId",
        "description": "ID of the webhook to debug",
        "required": true
      }
    ]
  }
  ```
</ResponseField>

## Rate Limits

* **Requests per minute:** 60
* **Concurrent connections:** 5
* **Response size:** 10MB max

## Error Handling

Errors follow the JSON-RPC 2.0 error format:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required parameter: webhookId"
    }
  }
}
```

### Common Error Codes

| Code   | Message           | Description                |
| ------ | ----------------- | -------------------------- |
| -32700 | Parse error       | Invalid JSON               |
| -32600 | Invalid request   | Invalid JSON-RPC           |
| -32601 | Method not found  | Unknown method             |
| -32602 | Invalid params    | Invalid parameters         |
| -32603 | Internal error    | Server error               |
| 401    | Unauthorized      | Invalid or missing API key |
| 429    | Too Many Requests | Rate limit exceeded        |

## Example Session

```bash theme={null}
# Initialize connection
curl -X POST https://app.unhook.sh/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{}}}'

# List resources
curl -X POST https://app.unhook.sh/api/mcp/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"2","method":"resources/list","params":{}}'

# Read events
curl -X POST https://app.unhook.sh/api/mcp/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"3","method":"resources/read","params":{"uri":"webhook://events/recent"}}'
```

## SDK Support

The MCP server is compatible with:

* [@modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk)
* Claude Desktop MCP client
* Cursor AI integration

## Webhooks Integration

The MCP server automatically scopes data access to your organization based on the API key. You can only access webhooks, events, and requests that belong to your organization.

## Next Steps

* Review the [Tool Reference](/api-reference/mcp/tools) for detailed tool documentation
* Check the [Resource Reference](/api-reference/mcp/resources) for resource schemas
* See [Integration Examples](/api-reference/mcp/examples) for common use cases


# MCP Resources Reference
Source: https://docs.unhook.sh/api-reference/mcp/resources

Data schemas and structures for MCP resources

# MCP Resources Reference

Resources provide read-only access to your webhook data. Each resource has a unique URI and returns structured data in a consistent format.

## Resource URIs

All resources follow the pattern: `webhook://[type]/[identifier]`

| URI                         | Description               |
| --------------------------- | ------------------------- |
| `webhook://events/recent`   | Last 100 webhook events   |
| `webhook://requests/recent` | Last 100 webhook requests |
| `webhook://webhooks/list`   | All configured webhooks   |

## webhook://events/recent

Returns the most recent webhook events across all your webhooks.

### Response Schema

```json theme={null}
{
  "uri": "webhook://events/recent",
  "mimeType": "application/json",
  "text": {
    "events": [
      {
        "id": "evt_1234567890",
        "webhookId": "wh_stripe_prod",
        "status": "success" | "failed" | "pending",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "provider": "stripe" | "github" | "clerk" | "custom",
        "eventType": "payment_intent.succeeded",
        "payload": {
          // Event-specific payload data
        },
        "error": "Connection timeout", // Only if status is failed
        "retryCount": 0,
        "nextRetryAt": "2024-01-15T10:35:00.000Z" // Only if retries scheduled
      }
    ],
    "metadata": {
      "count": 100,
      "hasMore": true,
      "oldestEventAt": "2024-01-15T08:00:00.000Z",
      "newestEventAt": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### Event Status Values

| Status    | Description                  |
| --------- | ---------------------------- |
| `success` | Event processed successfully |
| `failed`  | Event processing failed      |
| `pending` | Event queued for processing  |

### Provider Values

| Provider | Description                 |
| -------- | --------------------------- |
| `stripe` | Stripe payment webhooks     |
| `github` | GitHub repository events    |
| `clerk`  | Clerk authentication events |
| `custom` | Custom webhook providers    |

## webhook://requests/recent

Returns the most recent webhook HTTP requests made by your webhooks.

### Response Schema

```json theme={null}
{
  "uri": "webhook://requests/recent",
  "mimeType": "application/json",
  "text": {
    "requests": [
      {
        "id": "req_0987654321",
        "eventId": "evt_1234567890",
        "webhookId": "wh_stripe_prod",
        "status": "success" | "failed" | "timeout",
        "statusCode": 200,
        "duration": 245, // milliseconds
        "createdAt": "2024-01-15T10:30:05.000Z",
        "method": "POST",
        "url": "https://api.example.com/webhooks/stripe",
        "headers": {
          "content-type": "application/json",
          "x-stripe-signature": "...",
          "user-agent": "Stripe/1.0"
        },
        "requestBody": {
          // Request payload
        },
        "responseBody": {
          // Response payload
        },
        "error": "Connection refused" // Only if failed
      }
    ],
    "metadata": {
      "count": 100,
      "hasMore": true,
      "oldestRequestAt": "2024-01-15T08:00:05.000Z",
      "newestRequestAt": "2024-01-15T10:30:05.000Z"
    }
  }
}
```

### Request Status Values

| Status    | Description                        |
| --------- | ---------------------------------- |
| `success` | Request completed with 2xx status  |
| `failed`  | Request failed with 4xx/5xx status |
| `timeout` | Request timed out                  |

### Common Status Codes

| Code | Description                      |
| ---- | -------------------------------- |
| 200  | OK - Request successful          |
| 201  | Created - Resource created       |
| 400  | Bad Request - Invalid payload    |
| 401  | Unauthorized - Invalid signature |
| 404  | Not Found - Endpoint not found   |
| 500  | Internal Server Error            |
| 502  | Bad Gateway                      |
| 503  | Service Unavailable              |
| 504  | Gateway Timeout                  |

## webhook://webhooks/list

Returns all configured webhooks in your organization.

### Response Schema

```json theme={null}
{
  "uri": "webhook://webhooks/list",
  "mimeType": "application/json",
  "text": {
    "webhooks": [
      {
        "id": "wh_stripe_prod",
        "name": "Stripe Production",
        "description": "Production Stripe payment events",
        "provider": "stripe",
        "url": "https://unhook.sh/wh_stripe_prod",
        "targetUrl": "https://api.example.com/webhooks/stripe",
        "active": true,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-15T09:00:00.000Z",
        "configuration": {
          "retryEnabled": true,
          "maxRetries": 3,
          "retryDelay": 300, // seconds
          "timeout": 30, // seconds
          "headers": {
            "x-api-key": "***" // Sensitive values masked
          }
        },
        "stats": {
          "totalEvents": 1523,
          "successfulEvents": 1456,
          "failedEvents": 67,
          "lastEventAt": "2024-01-15T10:30:00.000Z"
        }
      }
    ],
    "metadata": {
      "count": 5,
      "activeWebhooks": 4,
      "inactiveWebhooks": 1
    }
  }
}
```

### Webhook Fields

<ResponseField name="id" type="string">
  Unique identifier for the webhook
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name
</ResponseField>

<ResponseField name="description" type="string">
  Optional description of the webhook's purpose
</ResponseField>

<ResponseField name="provider" type="string">
  The webhook provider (stripe, github, clerk, custom)
</ResponseField>

<ResponseField name="url" type="string">
  The Unhook URL to configure with the provider
</ResponseField>

<ResponseField name="targetUrl" type="string">
  Your endpoint that receives the webhooks
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the webhook is currently active
</ResponseField>

<ResponseField name="configuration" type="object">
  Webhook-specific configuration settings
</ResponseField>

<ResponseField name="stats" type="object">
  Basic statistics about webhook performance
</ResponseField>

## Data Limits

Resources are designed to provide quick access to recent data:

* **Events**: Limited to 100 most recent events
* **Requests**: Limited to 100 most recent requests
* **Webhooks**: No limit (typically \< 50 per organization)

For historical data or larger datasets, use the search tools instead.

## Common Patterns

### Checking Recent Failures

To quickly identify recent issues:

1. Read `webhook://events/recent`
2. Filter events with `status: "failed"`
3. Use event IDs to search for related requests

### Monitoring Webhook Health

To assess webhook performance:

1. Read `webhook://webhooks/list`
2. Check the `stats` field for each webhook
3. Identify webhooks with high failure rates

### Debugging Specific Events

To investigate a particular event:

1. Read `webhook://events/recent`
2. Find the event by ID or characteristics
3. Note the `webhookId` and `eventId`
4. Use tools to analyze the event details

## Error Responses

If a resource cannot be accessed, the response will include an error:

```json theme={null}
{
  "uri": "webhook://events/recent",
  "mimeType": "application/json",
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "No access to organization webhooks"
  }
}
```

### Common Error Codes

| Code                | Description             |
| ------------------- | ----------------------- |
| `NOT_FOUND`         | Resource does not exist |
| `PERMISSION_DENIED` | No access to resource   |
| `INTERNAL_ERROR`    | Server error occurred   |

## Best Practices

1. **Cache resource data** - Resources update in real-time, but caching for 30-60 seconds is acceptable
2. **Use metadata** - Check `hasMore` to know if older data exists
3. **Combine with tools** - Resources show recent data; use tools for historical analysis
4. **Monitor regularly** - Set up periodic checks of webhook health
5. **Handle errors gracefully** - Always check for error responses

## Next Steps

* See [Tools Reference](/api-reference/mcp/tools) for querying and analyzing data
* Check [Integration Examples](/api-reference/mcp/examples) for usage patterns
* Review [MCP Overview](/api-reference/mcp/overview) for protocol details


# MCP Tools Reference
Source: https://docs.unhook.sh/api-reference/mcp/tools

Detailed documentation for all MCP tools

# MCP Tools Reference

Tools allow AI assistants to perform actions and queries on your webhook data. Each tool has specific parameters and returns structured data.

## search\_events

Search and filter webhook events based on various criteria.

### Parameters

<ParamField type="string">
  Filter events by webhook ID (e.g., "wh\_123")
</ParamField>

<ParamField type="string">
  Filter by event status

  * `success` - Successfully processed events
  * `failed` - Failed events
  * `pending` - Events waiting to be processed
</ParamField>

<ParamField type="number">
  Maximum number of events to return (1-100)
</ParamField>

### Response

```json theme={null}
{
  "events": [
    {
      "id": "evt_123",
      "webhookId": "wh_456",
      "status": "failed",
      "createdAt": "2024-01-15T10:30:00Z",
      "provider": "stripe",
      "eventType": "payment_intent.succeeded",
      "error": "Connection timeout",
      "retryCount": 3
    }
  ],
  "total": 42,
  "hasMore": true
}
```

### Example Usage

```json theme={null}
{
  "name": "search_events",
  "arguments": {
    "webhookId": "wh_stripe_prod",
    "status": "failed",
    "limit": 50
  }
}
```

## search\_requests

Search webhook requests with filtering options.

### Parameters

<ParamField type="string">
  Filter requests by webhook ID
</ParamField>

<ParamField type="string">
  Filter requests by event ID
</ParamField>

<ParamField type="string">
  Filter by request status

  * `success` - Successful requests (2xx status codes)
  * `failed` - Failed requests (4xx, 5xx status codes)
  * `timeout` - Timed out requests
</ParamField>

<ParamField type="number">
  Maximum number of requests to return (1-100)
</ParamField>

### Response

```json theme={null}
{
  "requests": [
    {
      "id": "req_789",
      "eventId": "evt_123",
      "webhookId": "wh_456",
      "status": "failed",
      "statusCode": 500,
      "duration": 1523,
      "createdAt": "2024-01-15T10:30:05Z",
      "method": "POST",
      "url": "https://api.example.com/webhook",
      "headers": {
        "content-type": "application/json",
        "x-stripe-signature": "..."
      },
      "error": "Internal server error"
    }
  ],
  "total": 156,
  "hasMore": true
}
```

### Example Usage

```json theme={null}
{
  "name": "search_requests",
  "arguments": {
    "eventId": "evt_123",
    "status": "failed"
  }
}
```

## analyze\_event

Get detailed analysis of a specific webhook event.

### Parameters

<ParamField type="string">
  The ID of the event to analyze
</ParamField>

### Response

```json theme={null}
{
  "event": {
    "id": "evt_123",
    "webhookId": "wh_456",
    "status": "failed",
    "createdAt": "2024-01-15T10:30:00Z",
    "provider": "stripe",
    "eventType": "payment_intent.succeeded"
  },
  "requests": [
    {
      "id": "req_789",
      "status": "failed",
      "statusCode": 500,
      "duration": 1523,
      "createdAt": "2024-01-15T10:30:05Z"
    }
  ],
  "payload": {
    "id": "pi_123",
    "object": "payment_intent",
    "amount": 1000,
    "currency": "usd"
  },
  "analysis": {
    "failureReason": "Target endpoint returned 500 error",
    "retryable": true,
    "recommendations": [
      "Check target endpoint health",
      "Review server logs for errors",
      "Consider implementing retry logic"
    ]
  }
}
```

### Example Usage

```json theme={null}
{
  "name": "analyze_event",
  "arguments": {
    "eventId": "evt_123"
  }
}
```

## analyze\_request

Get detailed analysis of a specific webhook request.

### Parameters

<ParamField type="string">
  The ID of the request to analyze
</ParamField>

### Response

```json theme={null}
{
  "request": {
    "id": "req_789",
    "eventId": "evt_123",
    "webhookId": "wh_456",
    "status": "failed",
    "statusCode": 500,
    "duration": 1523,
    "createdAt": "2024-01-15T10:30:05Z",
    "method": "POST",
    "url": "https://api.example.com/webhook"
  },
  "requestHeaders": {
    "content-type": "application/json",
    "x-stripe-signature": "...",
    "user-agent": "Stripe/1.0"
  },
  "requestBody": {
    "id": "pi_123",
    "object": "payment_intent",
    "amount": 1000
  },
  "responseHeaders": {
    "content-type": "text/html",
    "server": "nginx/1.19.0"
  },
  "responseBody": "<html><body>Internal Server Error</body></html>",
  "analysis": {
    "issue": "Endpoint returned HTML error page instead of JSON",
    "possibleCauses": [
      "Application crashed",
      "Misconfigured error handling",
      "Database connection failure"
    ],
    "recommendations": [
      "Check application logs",
      "Verify webhook endpoint configuration",
      "Test endpoint manually with curl"
    ]
  }
}
```

### Example Usage

```json theme={null}
{
  "name": "analyze_request",
  "arguments": {
    "requestId": "req_789"
  }
}
```

## get\_webhook\_stats

Get comprehensive statistics for webhooks.

### Parameters

<ParamField type="string">
  Get stats for specific webhook (omit for all webhooks)
</ParamField>

<ParamField type="string">
  Time range for statistics

  * `1h` - Last hour
  * `24h` - Last 24 hours
  * `7d` - Last 7 days
  * `30d` - Last 30 days
</ParamField>

### Response

```json theme={null}
{
  "summary": {
    "totalEvents": 1523,
    "successfulEvents": 1456,
    "failedEvents": 67,
    "successRate": 0.956,
    "averageResponseTime": 245
  },
  "webhooks": [
    {
      "id": "wh_456",
      "name": "Stripe Production",
      "provider": "stripe",
      "stats": {
        "totalEvents": 892,
        "successfulEvents": 875,
        "failedEvents": 17,
        "successRate": 0.981,
        "averageResponseTime": 198
      }
    }
  ],
  "eventTypes": [
    {
      "type": "payment_intent.succeeded",
      "count": 456,
      "successRate": 0.993,
      "averageResponseTime": 167
    }
  ],
  "errorDistribution": [
    {
      "error": "Connection timeout",
      "count": 23,
      "percentage": 0.343
    },
    {
      "error": "500 Internal Server Error",
      "count": 19,
      "percentage": 0.284
    }
  ],
  "timeSeriesData": {
    "labels": ["2024-01-14T00:00:00Z", "2024-01-14T01:00:00Z"],
    "successful": [45, 52],
    "failed": [2, 1]
  }
}
```

### Example Usage

```json theme={null}
{
  "name": "get_webhook_stats",
  "arguments": {
    "webhookId": "wh_stripe_prod",
    "timeRange": "7d"
  }
}
```

## Error Handling

All tools return errors in a consistent format:

```json theme={null}
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid webhook ID format",
    "details": {
      "parameter": "webhookId",
      "value": "invalid",
      "expected": "Format: wh_xxx"
    }
  }
}
```

### Common Error Codes

| Code                | Description             |
| ------------------- | ----------------------- |
| `INVALID_PARAMETER` | Invalid parameter value |
| `NOT_FOUND`         | Resource not found      |
| `PERMISSION_DENIED` | No access to resource   |
| `RATE_LIMITED`      | Too many requests       |
| `INTERNAL_ERROR`    | Server error            |

## Best Practices

1. **Use filters effectively** - Always filter by webhookId when debugging specific integrations
2. **Limit results** - Start with smaller limits and increase if needed
3. **Check error details** - The analysis tools provide actionable recommendations
4. **Monitor stats regularly** - Use get\_webhook\_stats to track webhook health
5. **Combine tools** - Use search tools to find issues, then analyze tools for details

## Rate Limits

Tools are subject to the following limits:

* Maximum 60 tool calls per minute
* Maximum result size of 1MB per call
* Search results capped at 100 items

## Next Steps

* See [Resource Reference](/api-reference/mcp/resources) for data schemas
* Check [Integration Examples](/api-reference/mcp/examples) for common workflows
* Review [MCP Overview](/api-reference/mcp/overview) for protocol details


# Architecture
Source: https://docs.unhook.sh/architecture



## System Overview

Unhook consists of several key components working together to provide seamless webhook development:

<div>
  <img alt="Unhook Architecture" />
</div>

## Data Flow Steps

<Steps>
  <Step title="Webhook Reception">
    * Provider sends webhook to `https://unhook.sh/t_123?e=ENDPOINT`
    * API validates the API key and processes the request
    * Event is stored in the database
  </Step>

  <Step title="Real-time Distribution">
    * CLI clients subscribe to new events
    * Database triggers notify connected clients
    * Events are delivered to local development servers
  </Step>

  <Step title="Local Processing">
    * CLI delivers requests to specified port or URL
    * Responses are captured and stored
    * Results are visible in the dashboard
  </Step>
</Steps>

## Database Schema

### Core Entities

#### Users and Organizations

#### Webhooks and Connections

### Key Tables

#### Users

```typescript theme={null}
interface User {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  online: boolean;
  lastLoggedInAt?: Date;
}
```

#### Organizations

```typescript theme={null}
interface Org {
  id: string;
  createdByUserId: string;
  clerkOrgId?: string;
}
```

#### Webhooks

```typescript theme={null}
interface Webhook {
  id: string;
  clientId: string;
  port: number;
  status: 'active' | 'inactive';
  localConnectionStatus: 'connected' | 'disconnected';
  config: WebhookConfig;
  userId: string;
  orgId: string;
}
```

#### Events

```typescript theme={null}
interface Event {
  id: string;
  webhookId: string;
  originalRequest: RequestPayload;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  retryCount: number;
  maxRetries: number;
}
```

### Configuration Types

#### Webhook Configuration

```typescript theme={null}
interface WebhookConfig {
  storage: {
    storeHeaders: boolean;
    storeRequestBody: boolean;
    storeResponseBody: boolean;
    maxRequestBodySize: number;
    maxResponseBodySize: number;
  };
  headers: {
    allowList?: string[];
    blockList?: string[];
    sensitiveHeaders?: string[];
  };
  requests: {
    allowedMethods?: string[];
    allowedFrom?: string[];
    blockedFrom?: string[];
    maxRequestsPerMinute?: number;
    maxRetries?: number;
  };
}
```

## Component Architecture

### API Server

The API server handles:

* Webhook reception and validation
* Event storage and distribution
* Authentication and authorization
* Team management
* Real-time updates

### CLI Client

The CLI client manages:

* Local webhook connections
* Event subscription
* Request delivery
* Health monitoring
* Debug logging

### Dashboard

The web dashboard provides:

* Real-time event monitoring
* Team management
* Configuration controls
* Analytics and debugging
* Request/response inspection

## Security Model

1. **API Authentication**
   * API keys for webhook endpoints
   * JWT tokens for dashboard access
   * Role-based access control

2. **Data Privacy**
   * Configurable header filtering
   * Request/response body size limits
   * Sensitive data redaction

3. **Team Access**
   * Organization-based isolation
   * Member role management
   * Shared webhook endpoints

## Scaling Considerations

1. **Database**
   * Real-time notification system
   * Event archival strategy
   * Connection pooling

2. **API Layer**
   * Request rate limiting
   * Load balancing
   * Regional distribution

3. **Event Processing**
   * Retry mechanisms
   * Failure handling
   * Queue management

## Development Setup

For local development:

1. **Database**

```bash theme={null}
# Start Postgres
docker compose up db
```

2. **API Server**

```bash theme={null}
# Start API server
npm run dev:api
```

3. **CLI Development**

```bash theme={null}
# Build and run CLI
npm run dev:cli
```

## Best Practices

1. **Event Handling**
   * Implement proper retry logic
   * Handle timeouts gracefully
   * Log relevant debugging info

2. **Security**
   * Rotate API keys regularly
   * Monitor failed attempts
   * Review access logs

3. **Team Workflow**
   * Use meaningful client IDs
   * Configure appropriate timeouts
   * Set up health checks


# CLI Reference
Source: https://docs.unhook.sh/cli

Command line interface for Unhook

## Installation

Install the Unhook CLI globally using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @unhook/cli
  ```

  ```bash yarn theme={null}
  yarn global add @unhook/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @unhook/cli
  ```

  ```bash bun theme={null}
  bun add -g @unhook/cli
  ```

  ```bash deno theme={null}
  deno install @unhook/cli
  ```
</CodeGroup>

## Quick Start

1. Initialize your project:

```bash theme={null}
npx @unhook/cli init
```

2. Start the webhook:

```bash theme={null}
npx @unhook/cli listen
```

3. Use the generated webhook URL in your provider's settings:

```bash theme={null}
https://unhook.sh/your_webhook_id
```

## Core Commands

### `unhook init`

Authenticate with Unhook and set up your project. Creates an `unhook.yml` config and guides you through connecting your webhook provider.

```bash theme={null}
unhook init [options]

Options:
  -c, --code         Authentication code for direct login (advanced; usually not needed)
  -t, --destination  Set the local destination URL to forward webhooks to (e.g., "http://localhost:3000/api/webhooks")
  -s, --source       Set the source name or URL for incoming webhooks (e.g., "stripe")
  -w, --webhook      Specify a webhook ID to use (optional; usually auto-generated)
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables browser prompts, interactive forms)
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
```

**Examples:**

```bash theme={null}
# Basic initialization
npx @unhook/cli init

# With custom destination
npx @unhook/cli init --destination http://localhost:3000/api/webhooks

# With specific source
npx @unhook/cli init --source stripe

# With custom webhook ID
npx @unhook/cli init --webhook custom_id

# Non-interactive mode (useful for CI/CD)
npx @unhook/cli init --non-interactive --destination http://localhost:3000/api/webhooks

# Non-interactive mode with API key authentication
npx @unhook/cli init --non-interactive --api-key your_api_key --destination http://localhost:3000/api/webhooks
```

### `unhook listen`

Start the Unhook relay to receive and forward webhooks to your local server. Keeps the CLI running and displays incoming requests.

```bash theme={null}
unhook listen [options]

Options:
  -c, --config       Path to a custom unhook.yml configuration file
  --path             Directory to watch for config changes (default: ".")
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables keyboard navigation)
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
```

**Examples:**

```bash theme={null}
# Basic usage
npx @unhook/cli listen

# With custom config file
npx @unhook/cli listen --config ./custom/unhook.yml

# With custom directory
npx @unhook/cli listen --path ./config

# With debug logging
npx @unhook/cli listen --verbose
```

### `unhook login`

Authenticate your CLI with your Unhook account. Opens a browser for login (unless in non-interactive mode).

```bash theme={null}
unhook login [options]

Options:
  -c, --code         Authentication code for direct login (advanced; usually not needed)
  -k, --api-key      API key or token for authentication (non-interactive mode)
  -y, --non-interactive  Enable non-interactive mode (disables browser opening)
  -v, --verbose      Enable verbose debug logging for troubleshooting
  -h, --help         Show help
```

**Examples:**

```bash theme={null}
# Basic login
npx @unhook/cli login

# With authentication code
npx @unhook/cli login --code your_auth_code

# Non-interactive login with API key
npx @unhook/cli login --non-interactive --api-key your_api_key
```

## Global Options

| Option              | Alias | Description                                                                                                                         | Default |
| ------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--verbose`         | `-v`  | Enable verbose debug logging for troubleshooting                                                                                    | `false` |
| `--non-interactive` | `-y`  | Enable non-interactive mode. Disables browser prompts, interactive forms, and user input. Automatically enabled in CI environments. | `false` |
| `--api-key`         | `-k`  | API key or token for authentication in non-interactive mode. Can also be set via `UNHOOK_API_KEY` environment variable.             | -       |
| `--help`            | `-h`  | Show help                                                                                                                           | -       |
| `--version`         | -     | Show version number                                                                                                                 | -       |

## Configuration

### Configuration File

The CLI uses an `unhook.yml` file for configuration. This file should be in your project root:

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

### Configuration File Locations

The CLI 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)

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

## Interactive UI

The CLI includes an interactive terminal UI that shows:

* Connection status
* Webhook activity
* Error messages
* Debug information (when enabled)

### UI Elements

* **Status Bar**: Shows connection status and client ID
* **Activity Log**: Real-time webhook request log
* **Debug Panel**: Detailed debug information (visible with `--verbose`)
* **Error Messages**: Highlighted in red for visibility

### Navigation

* **Arrow Keys**: Navigate through lists and menus
* **Enter**: Select items or execute actions
* **ESC**: Go back to previous screen
* **q**: Quit the application
* **?**: Show keyboard shortcuts

## Health Checks

The `ping` option in your configuration configures connection health monitoring:

```yaml theme={null}
destination:
  - name: local
    url: http://localhost:3000/api/webhooks
    ping: true  # Enable default health check

  - name: custom
    url: http://localhost:3001/api/webhooks
    ping: http://localhost:3001/health  # Custom health check URL
```

## Authentication

The CLI supports multiple authentication methods:

### Interactive Authentication (Default)

In interactive mode, the CLI uses OAuth browser-based authentication:

1. Run `npx @unhook/cli login` or `npx @unhook/cli init`
2. A browser window opens for authentication
3. Complete the OAuth flow in your browser
4. The CLI automatically receives the authentication token

### Non-Interactive Authentication

For CI/CD pipelines, automated scripts, or environments without browser access, use API key authentication:

**Using API key flag:**

```bash theme={null}
npx @unhook/cli init --non-interactive --api-key your_api_key --destination http://localhost:3000
```

**Using environment variable:**

```bash theme={null}
export UNHOOK_API_KEY=your_api_key
npx @unhook/cli init --non-interactive --destination http://localhost:3000
```

**Using authentication code:**

```bash theme={null}
npx @unhook/cli login --non-interactive --code your_auth_code
```

<Note>
  In non-interactive mode, if no API key or authentication code is provided, the CLI will display an error message with instructions on how to authenticate.
</Note>

### Authentication Storage

Authentication data is stored locally at `~/.unhook/auth-storage.json`:

* Authentication state
* User tokens
* Organization ID
* Basic user info

To clear auth data:

```bash theme={null}
rm ~/.unhook/auth-storage.json
```

## Exit Codes

| Code | Description           |
| ---- | --------------------- |
| 0    | Success               |
| 1    | General error         |
| 2    | Invalid configuration |
| 3    | Network error         |
| 4    | Authentication error  |

## Examples

### Basic Development Setup

```bash theme={null}
# Initialize project
npx @unhook/cli init

# Start webhook
npx @unhook/cli listen
```

### Team Development

```bash theme={null}
# Developer 1
npx @unhook/cli init --webhook team_webhook_id
npx @unhook/cli listen

# Developer 2
npx @unhook/cli init --webhook team_webhook_id
npx @unhook/cli listen
```

### Custom Configuration

```bash theme={null}
# Use custom config file
npx @unhook/cli listen --config ./config/unhook.yml

# Watch custom directory
npx @unhook/cli listen --path ./config
```

### Debug Mode

```bash theme={null}
# Enable debug logging
npx @unhook/cli listen --verbose

# Debug initialization
npx @unhook/cli init --verbose
```

### CI/CD and Non-Interactive Usage

```bash theme={null}
# Non-interactive initialization with API key
export UNHOOK_API_KEY=your_api_key
npx @unhook/cli init --non-interactive --destination http://localhost:3000/api/webhooks

# Non-interactive initialization with all options
npx @unhook/cli init \
  --non-interactive \
  --api-key $UNHOOK_API_KEY \
  --destination http://localhost:3000/api/webhooks \
  --source stripe \
  --webhook my-webhook-id

# Non-interactive login
npx @unhook/cli login --non-interactive --api-key $UNHOOK_API_KEY
```

<Note>
  Non-interactive mode is automatically enabled when the `CI` environment variable is set to `true`, making it seamless for CI/CD pipelines.
</Note>

## Best Practices

1. **Use Configuration Files**: Store your settings in `unhook.yml` for consistency
2. **Enable Debug Logging**: Use `--verbose` when troubleshooting issues
3. **Health Checks**: Configure appropriate health checks for your setup
4. **Environment Variables**: Use env vars for sensitive information (e.g., `UNHOOK_API_KEY`)
5. **Team Configuration**: Share configuration files in version control
6. **CI/CD Authentication**: Use API keys in CI/CD environments instead of browser-based OAuth
7. **Non-Interactive Mode**: Use `--non-interactive` flag or set `CI=true` for automated environments

## Troubleshooting

### Common Issues

1. **Connection Issues**
   * Check your internet connection
   * Verify the webhook ID is correct
   * Ensure the port is available

2. **Authentication Problems**
   * Clear auth data: `rm ~/.unhook/auth-storage.json`
   * Re-run initialization: `npx @unhook/cli init`

3. **Configuration Issues**
   * Verify YAML syntax in `unhook.yml`
   * Check file permissions
   * Ensure required fields are present

4. **Debug Mode**
   * Enable debug logging: `npx @unhook/cli listen --verbose`
   * Check the debug panel for detailed information

### Getting Help

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

## Support

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


# Configuration
Source: https://docs.unhook.sh/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)


# Contributing
Source: https://docs.unhook.sh/contributing

Contribute to Unhook and run it locally

<Info>
  **Prerequisites**:

  * Node.js (version 18 or higher)
  * Git
  * A webhook provider account (Stripe, GitHub, etc.) for testing
</Info>

## Local Development Setup

### Clone the Repository

First, clone the Unhook repository and install dependencies:

<CodeGroup>
  ```bash npm theme={null}
  git clone https://github.com/unhook-sh/unhook.git
  cd unhook
  npm install
  ```

  ```bash yarn theme={null}
  git clone https://github.com/unhook-sh/unhook.git
  cd unhook
  yarn install
  ```

  ```bash pnpm theme={null}
  git clone https://github.com/unhook-sh/unhook.git
  cd unhook
  pnpm install
  ```
</CodeGroup>

### Start the Development Server

Run the development server locally:

```bash theme={null}
npm run dev
```

This will start:

* The CLI webhook service on port 3000
* The web dashboard on port 3001
* The webhook processing service on port 3002

## Project Structure

```plaintext theme={null}
unhook/
├── packages/
│   ├── cli/          # Command line interface
│   ├── core/         # Core webhook processing logic
│   ├── dashboard/    # Web dashboard (Next.js)
│   └── shared/       # Shared utilities and types
├── examples/         # Example integrations
└── docs/            # Documentation
```

## Development Workflow

### Running Tests

Tests are powered by **Vitest** and executed with `bun test`. Run the test suite with:

```bash theme={null}
# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests for a specific package
bun test packages/cli
```

### Linting and Formatting

We use ESLint and Prettier to maintain code quality:

```bash theme={null}
# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## Building Locally

To build all packages:

```bash theme={null}
npm run build
```

To build a specific package:

```bash theme={null}
npm run build --workspace=@unhook/cli
```

## Running Examples

We provide example integrations in the `examples/` directory. To run an example:

```bash theme={null}
# Navigate to an example
cd examples/stripe-webhook

# Install dependencies
npm install

# Start the example
npm run dev
```

## Debugging

### CLI Debugging

Run the CLI with debug logging:

```bash theme={null}
# Using npm
npm run dev:cli -- --debug

# Direct binary
./packages/cli/bin/run --debug
```

### Dashboard Debugging

The dashboard includes React Developer Tools and runs in development mode by default:

```bash theme={null}
# Start dashboard in development mode
npm run dev:dashboard
```

## Common Issues

<AccordionGroup>
  <Accordion title="Error: Port already in use">
    If port 3000, 3001, or 3002 is already in use, you can specify different ports:

    ```bash theme={null}
    # For CLI
    npm run dev:cli -- --port 4000

    # For dashboard
    PORT=4001 npm run dev:dashboard

    # For webhook service
    WEBHOOK_PORT=4002 npm run dev:service
    ```
  </Accordion>

  <Accordion title="Error: Invalid API Key">
    During development, you can use test API keys:

    ```bash theme={null}
    # Test mode
    npm run dev:cli -- --webhook-id t_test_123
    ```
  </Accordion>
</AccordionGroup>

## Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Run tests: `bun test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to your branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Contribution Guidelines

* Follow the existing code style
* Add tests for new features
* Update documentation for changes
* Keep commits focused and atomic
* Write clear commit messages

## Next Steps

<CardGroup>
  <Card title="Architecture" icon="diagram-project" href="/architecture">
    Learn about Unhook's internal architecture
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the internal APIs
  </Card>

  <Card title="Testing Guide" icon="vial" href="/testing">
    Learn how to test your changes
  </Card>

  <Card title="Provider Development" icon="plug" href="/provider-dev">
    Create integrations for new webhook providers
  </Card>
</CardGroup>


# Cross-Platform CLI Setup
Source: https://docs.unhook.sh/cross-platform-setup

Implementation guide for cross-platform CLI binary distribution and installation

## Overview

The `@unhook/cli` package has been enhanced to work seamlessly across all major platforms (macOS, Windows, Linux, ARM/x64) using a hybrid approach that downloads platform-specific binaries during installation.

## Architecture

### Build System

* **GitHub Actions**: Builds binaries for all supported platforms
* **Release Assets**: Uploads binaries to GitHub releases with standardized naming
* **Platforms Supported**:
  * `linux-x64` (glibc)
  * `linux-arm64` (glibc)
  * `linux-x64-musl` (Alpine Linux)
  * `linux-arm64-musl` (Alpine Linux ARM64)
  * `darwin-x64` (macOS Intel)
  * `darwin-arm64` (macOS Apple Silicon)
  * `win32-x64` (Windows 64-bit)

### Installation Flow

<Steps>
  <Step title="Package Installation">
    User runs `npm install @unhook/cli`
  </Step>

  <Step title="Postinstall Hook">
    `scripts/install.cjs` executes automatically
  </Step>

  <Step title="Platform Detection">
    Detects OS, architecture, and libc variant (musl vs glibc)
  </Step>

  <Step title="Binary Download">
    Downloads appropriate binary from GitHub releases
  </Step>

  <Step title="Installation">
    Stores binary in `~/.unhook/bin/{version}/` with proper permissions
  </Step>
</Steps>

### Runtime Flow

<Steps>
  <Step title="Command Execution">
    User runs `unhook [command]`
  </Step>

  <Step title="Wrapper Execution">
    `bin/cli.cjs` wrapper script executes
  </Step>

  <Step title="Binary Location">
    Wrapper detects platform and locates downloaded binary
  </Step>

  <Step title="Transparent Execution">
    Spawns platform-specific binary with user arguments
  </Step>

  <Step title="Result Return">
    Returns binary exit code transparently to user
  </Step>
</Steps>

## File Structure

```
apps/cli/
├── bin/
│   └── cli.cjs                 # CommonJS CLI wrapper
├── scripts/
│   └── install.cjs             # Installation script
├── tests/
│   └── integration/
│       └── cross-platform.test.ts  # Integration tests
├── package.json                # Updated configuration
└── README.md                   # User documentation
```

## Implementation Details

### Platform Detection

The CLI intelligently detects the target platform and architecture:

```javascript theme={null}
const platformMap = { win32: 'win32', darwin: 'darwin', linux: 'linux' };
const archMap = { x64: 'x64', arm64: 'arm64' };

// Linux-specific: Detect musl vs glibc
if (platform === 'linux') {
  if (fs.existsSync('/lib/ld-musl-x86_64.so.1') || 
      fs.existsSync('/lib/ld-musl-aarch64.so.1')) {
    targetArch = `${arch}-musl`;
  }
}
```

### Binary Naming Convention

Binaries follow this pattern: `unhook-{platform}-{arch}[.exe]`

<CardGroup>
  <Card title="macOS Examples">
    * `unhook-darwin-arm64` (Apple Silicon)
    * `unhook-darwin-x64` (Intel)
  </Card>

  <Card title="Linux Examples">
    * `unhook-linux-x64` (glibc)
    * `unhook-linux-x64-musl` (Alpine)
    * `unhook-linux-arm64` (ARM64 glibc)
    * `unhook-linux-arm64-musl` (ARM64 Alpine)
  </Card>

  <Card title="Windows Examples">
    * `unhook-win32-x64.exe` (64-bit)
  </Card>
</CardGroup>

### Version Management

* Binaries are stored in versioned directories: `~/.unhook/bin/{version}/`
* Old versions are automatically cleaned up during installation
* Multiple versions can coexist temporarily during upgrades

## Edge Cases & Robustness

### Network Issues

<AccordionGroup>
  <Accordion title="Corporate Firewalls">
    **Problem**: Users behind corporate firewalls or with poor connectivity

    **Solution**:

    * Respect `HTTP_PROXY`, `HTTPS_PROXY` environment variables
    * 30-second timeout with clear error messages
    * Graceful fallback with manual install instructions

    ```javascript theme={null}
    request.setTimeout(30000, () => {
      console.error('❌ Download timeout: The download took too long. Please try again.');
      process.exit(1);
    });
    ```
  </Accordion>

  <Accordion title="Permission Issues">
    **Problem**: Users without write permissions to home directory

    **Solution**:

    * Clear error messages with specific instructions
    * Platform-specific guidance (sudo on Linux/macOS, admin on Windows)
    * Alternative installation paths suggested
  </Accordion>
</AccordionGroup>

### Platform-Specific Handling

<Tabs>
  <Tab title="macOS">
    **Security (Gatekeeper)**:

    ```javascript theme={null}
    // Remove quarantine attribute
    execSync(`xattr -d com.apple.quarantine "${binPath}"`, { stdio: 'ignore' });
    ```

    **Code Signing**: macOS binaries are signed and notarized during CI
  </Tab>

  <Tab title="Linux">
    **Libc Detection**:

    ```javascript theme={null}
    // Detect musl by checking for loader
    if (fs.existsSync('/lib/ld-musl-x86_64.so.1')) {
      targetArch = `${arch}-musl`;
    }
    ```

    **Variants**: Support both glibc and musl variants for Alpine Linux compatibility
  </Tab>

  <Tab title="Windows">
    **Executable Extensions**:

    ```javascript theme={null}
    const ext = os.platform() === 'win32' ? '.exe' : '';
    ```

    **Permission Handling**: Windows-specific permission management
  </Tab>
</Tabs>

### CI/CD Environments

**Problem**: CI systems shouldn't download binaries during installation

**Solution**:

```javascript theme={null}
// Skip installation in CI
if (require('is-ci')) {
  process.exit(0);
}
```

## Testing Strategy

### Integration Tests

Comprehensive test suite covering:

1. **Platform Detection**: Verify correct platform/arch identification
2. **URL Construction**: Ensure proper download URLs
3. **Error Handling**: Test failure scenarios
4. **Package Configuration**: Validate package.json settings
5. **Platform-Specific Behavior**: Test OS-specific features

### Test Execution

```bash theme={null}
# Run all integration tests
bun test tests/integration/cross-platform.test.ts

# Run with coverage
bun test --coverage tests/integration/
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Binary not found&#x22; errors">
    ```bash theme={null}
    # Force reinstall
    npm install @unhook/cli --force

    # Manual install
    node ./node_modules/@unhook/cli/scripts/install.cjs
    ```
  </Accordion>

  <Accordion title="Permission denied on Linux/macOS">
    ```bash theme={null}
    chmod +x ~/.unhook/bin/*/unhook-*
    ```
  </Accordion>

  <Accordion title="macOS security warnings">
    ```bash theme={null}
    xattr -d com.apple.quarantine ~/.unhook/bin/*/unhook-darwin-*
    ```
  </Accordion>

  <Accordion title="Corporate proxy issues">
    ```bash theme={null}
    export HTTP_PROXY=http://proxy.company.com:8080
    export HTTPS_PROXY=http://proxy.company.com:8080
    npm install @unhook/cli
    ```
  </Accordion>
</AccordionGroup>

## Performance Considerations

<CardGroup>
  <Card title="One-time Download" icon="download">
    Binaries are cached locally after first install
  </Card>

  <Card title="Version Management" icon="clock-rotate-left">
    Only current version kept, old versions cleaned up
  </Card>

  <Card title="Efficient Detection" icon="gauge-high">
    Fast platform/arch detection using Node.js APIs
  </Card>

  <Card title="Minimal Overhead" icon="timer">
    CLI wrapper adds \~10ms startup time
  </Card>
</CardGroup>

## Security Considerations

<Warning>
  All security measures are implemented to ensure safe binary distribution:
</Warning>

* **Verified Downloads**: Binaries downloaded from official GitHub releases only
* **Code Signing**: macOS binaries are signed and notarized
* **No Build Tools Required**: Users don't need compilers or build chains
* **Quarantine Removal**: Automatic handling of macOS security restrictions

## Future Enhancements

1. **Checksum Verification**: Verify binary integrity using SHA checksums
2. **Delta Updates**: Only download changed parts of binaries
3. **Mirror Support**: Allow alternative download sources
4. **Offline Mode**: Bundle common binaries with the package
5. **Auto-updates**: Automatic binary updates when package is updated

## Contributing

When adding support for new platforms:

<Steps>
  <Step title="Update CI">
    Update the GitHub Actions workflow (`.github/workflows/cli-github-release.yml`)
  </Step>

  <Step title="Add Platform Mapping">
    Add platform mapping in both `install.cjs` and `cli.cjs`
  </Step>

  <Step title="Update Documentation">
    Update documentation and tests
  </Step>

  <Step title="Test on Platform">
    Test on the target platform before releasing
  </Step>
</Steps>

## References

* [GitHub Releases API](https://docs.github.com/en/rest/releases)
* [Node.js os module](https://nodejs.org/api/os.html)
* [npm postinstall hooks](https://docs.npmjs.com/cli/v7/using-npm/scripts)
* [Bun build targets](https://bun.sh/docs/bundler)


# Data Model
Source: https://docs.unhook.sh/essentials/data-model



# Data Model

This document explains the core data entities in Unhook and how they relate to each other.

## Entity Relationships

```mermaid theme={null}
flowchart TD
    subgraph Webhook[Webhook]
        T[id: string<br/>clientId: string<br/>webhookId: string<br/>port: number<br/>status: string]
    end

    subgraph Event[Event]
        E[id: string<br/>webhookId: string<br/>originalRequest: RequestPayload<br/>status: string]
    end

    subgraph Request[Request]
        R[id: string<br/>webhookId: string<br/>eventId: string<br/>request: RequestPayload<br/>status: string]
    end

    Webhook -->|1:Many| Event
    Event -->|1:Many| Request
    Webhook -->|1:Many| Request
```

## Core Entities

### Webhook Entity

The primary entity that manages webhook routing and configuration.

<ParamField type="string">
  Unique identifier with 't' prefix
</ParamField>

<ParamField type="string">
  Client identifier for routing
</ParamField>

<ParamField type="string">
  Associated webhook ID
</ParamField>

<ParamField type="number">
  Local port to deliver requests to
</ParamField>

<ParamField type="string">
  Current webhook status. Can be 'active' or 'inactive'
</ParamField>

<ParamField type="string">
  Connection status. Can be 'connected' or 'disconnected'
</ParamField>

<ParamField type="object">
  Webhook configuration object

  ```typescript theme={null}
  {
    storage: {
      storeHeaders: boolean;
      storeRequestBody: boolean;
      storeResponseBody: boolean;
      maxRequestBodySize: number;  // in bytes
      maxResponseBodySize: number; // in bytes
    };
    headers: {
      allowList?: string[];       // Only store these headers
      blockList?: string[];       // Never store these headers
      sensitiveHeaders?: string[]; // Replace with "[REDACTED]"
    };
    requests: {
      allowedMethods?: string[];  // Only allow specific HTTP methods
      allowedFrom?: string[];    // Only allow specific paths
      blockedFrom?: string[];    // Block specific paths
      maxRequestsPerMinute?: number;
      maxRetries?: number;
    };
  }
  ```
</ParamField>

<ParamField type="string">
  Owner user ID
</ParamField>

<ParamField type="string">
  Organization ID
</ParamField>

### Event Entity

Represents a webhook notification received by the system.

<ParamField type="string">
  Unique identifier with 'evt' prefix
</ParamField>

<ParamField type="string">
  Associated webhook ID
</ParamField>

<ParamField type="object">
  Original incoming webhook data (RequestPayload)
</ParamField>

<ParamField type="string">
  Current status. Can be 'pending', 'processing', 'completed', or 'failed'
</ParamField>

<ParamField type="number">
  Number of retry attempts made
</ParamField>

<ParamField type="number">
  Maximum allowed retries
</ParamField>

<ParamField type="string">
  Failure explanation if applicable
</ParamField>

<ParamField type="string">
  When the event was received (ISO date string)
</ParamField>

### Request Entity

Represents an attempt to deliver a webhook to a local development environment.

<ParamField type="string">
  Unique identifier with 'req' prefix
</ParamField>

<ParamField type="string">
  Associated webhook ID
</ParamField>

<ParamField type="string">
  Associated event ID
</ParamField>

<ParamField type="string">
  Associated webhook ID
</ParamField>

<ParamField type="string">
  Active connection ID if applicable
</ParamField>

<ParamField type="object">
  Request details (RequestPayload)
</ParamField>

<ParamField type="string">
  Current status. Can be 'pending', 'completed', or 'failed'
</ParamField>

<ParamField type="object">
  Response if completed (ResponsePayload)
</ParamField>

<ParamField type="number">
  Response time in milliseconds
</ParamField>

<ParamField type="string">
  When the request was made (ISO date string)
</ParamField>

<ParamField type="string">
  When the request completed (ISO date string)
</ParamField>

### RequestPayload Entity

<ParamField type="string">
  Unique request identifier
</ParamField>

<ParamField type="string">
  HTTP method used
</ParamField>

<ParamField type="string">
  Request URL
</ParamField>

<ParamField type="object">
  HTTP headers as key-value pairs
</ParamField>

<ParamField type="number">
  Request size in bytes
</ParamField>

<ParamField type="string">
  Base64 encoded request body
</ParamField>

<ParamField type="number">
  Unix timestamp of the request
</ParamField>

<ParamField type="string">
  Content-Type of the request
</ParamField>

<ParamField type="string">
  IP address of the client
</ParamField>

## Data Flow

<Steps>
  <Step title="Webhook Reception">
    * System creates an Event with the original request
    * Event is associated with the target Webhook
    * Initial status is set to 'pending'
  </Step>

  <Step title="Processing">
    * System creates a Request for delivery attempt
    * Request inherits Event and Webhook properties
    * System attempts to deliver to local environment
  </Step>

  <Step title="Completion">
    * Request status updated to 'completed' or 'failed'
    * Event status updated based on Request outcome
    * If failed and retries available, new Request created
  </Step>
</Steps>

## Security Considerations

<CardGroup>
  <Card title="API Keys" icon="key">
    API keys are required for webhook reception and authentication
  </Card>

  <Card title="Header Protection" icon="shield-halved">
    Sensitive headers can be redacted via configuration
  </Card>

  <Card title="Size Limits" icon="ruler">
    Request/response body size limits enforced
  </Card>

  <Card title="Organization Isolation" icon="building">
    Organization-level isolation of data
  </Card>

  <Card title="Access Control" icon="users">
    User-level access control to resources
  </Card>
</CardGroup>


# Introduction
Source: https://docs.unhook.sh/introduction

Simplify webhook development for your entire team

<img alt="Hero Light" />

<img alt="Hero Dark" />

## What is Unhook?

Unhook is an open-source tool that makes testing webhooks during local development simple and secure. Perfect for teams - share a single webhook endpoint while everyone tests locally.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started in seconds with a simple CLI command
  </Card>

  <Card title="Team Features" icon="users" href="/team-features">
    Share webhook URLs across your entire development team
  </Card>
</CardGroup>

## Key Features

Unhook provides everything you need for efficient webhook development.

<CardGroup>
  <Card title="Smart Distribution" icon="route" href="/features/routing">
    Automatically routes webhooks to the right developer's machine
  </Card>

  <Card title="Real-time Dashboard" icon="gauge" href="/features/dashboard">
    Monitor and debug webhook requests in real-time
  </Card>

  <Card title="End-to-End Security" icon="shield" href="/security">
    Built with security-first principles and encrypted traffic
  </Card>

  <Card title="Provider Support" icon="plug" href="/providers">
    Works with Stripe, GitHub, Clerk, and many more providers
  </Card>
</CardGroup>

## Getting Started

The fastest way to get started with Unhook is through our CLI:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @unhook/cli
  ```

  ```bash yarn theme={null}
  yarn add @unhook/cli
  ```

  ```bash pnpm theme={null}
  pnpm add @unhook/cli
  ```

  ```bash bun theme={null}
  bun add @unhook/cli
  ```

  ```bash deno theme={null}
  deno install @unhook/cli
  ```
</CodeGroup>

```bash theme={null}
# Start the webhook
unhook listen
```

Visit our [Quick Start](/quickstart) guide to learn more about setting up Unhook for your team.


# JetBrains Extension
Source: https://docs.unhook.sh/jetbrains-extension

The complete guide to using Unhook's JetBrains plugin for webhook development

# Unhook JetBrains Plugin

<div>
  <img alt="Unhook JetBrains Plugin" />
</div>

The Unhook JetBrains plugin brings powerful webhook development capabilities directly into your JetBrains IDE. Test, debug, and collaborate on webhooks without leaving your development environment.

## Features Overview

### 🎯 **Webhook Event Tool Window**

* Dedicated tool window for viewing all webhook events
* Real-time updates as events are received
* Hierarchical table view with sortable columns
* Event filtering and search capabilities

### 🔄 **Request Replay & Debugging**

* Instantly replay webhook events with a single click
* Detailed request/response inspection panel
* Copy event data to clipboard for analysis
* Support for debugging failed webhook deliveries

### 👥 **Team Collaboration**

* See active team members and their webhook sessions
* Share webhook URLs while maintaining individual environments
* Real-time collaboration features

### 🔐 **Secure Authentication**

* OAuth-based authentication with Unhook
* Secure session management and token handling
* Automatic session validation and refresh

### ⚙️ **Smart Configuration**

* Automatic detection of Unhook config files in workspace
* Configurable settings through IDE preferences
* Integration with JetBrains settings system

### 📊 **Real-Time Monitoring**

* Live webhook event monitoring in the tool window
* Status bar integration showing connection status
* Configurable notifications for new events

## Installation

### From JetBrains Marketplace

1. Open your JetBrains IDE (IntelliJ IDEA, WebStorm, PhpStorm, etc.)
2. Go to **File → Settings → Plugins** (or **IntelliJ IDEA → Preferences → Plugins** on macOS)
3. Click the **Marketplace** tab
4. Search for "Unhook - Webhook Development"
5. Click **Install**
6. Restart your IDE when prompted

### From ZIP File

If you have a plugin ZIP file:

1. Go to **File → Settings → Plugins** (or **IntelliJ IDEA → Preferences → Plugins** on macOS)
2. Click the gear icon ⚙️ and select **Install Plugin from Disk...**
3. Select the downloaded ZIP file
4. Restart your IDE

## Supported IDEs

The Unhook plugin is compatible with all JetBrains IDEs:

* **IntelliJ IDEA** (Community & Ultimate)
* **WebStorm**
* **PhpStorm**
* **PyCharm** (Community & Professional)
* **RubyMine**
* **CLion**
* **GoLand**
* **DataGrip**
* **Android Studio**
* **Rider**

**Requirements**: JetBrains IDE 2024.2 or later

## Getting Started

### 1. Authentication

After installation, you'll need to authenticate with Unhook:

1. **Open the Unhook tool window** - Go to **View → Tool Windows → Unhook**
2. **Sign in** - Click "Sign in to Unhook" in the status bar or use **Tools → Unhook → Sign In**
3. **Complete OAuth flow** - Your browser will open to complete authentication
4. **Return to IDE** - The plugin will automatically detect the successful authentication

<Note>
  If you don't have an Unhook account, you can create one for free at [unhook.sh](https://unhook.sh)
</Note>

### 2. Configure Your Project

The plugin will automatically look for Unhook configuration files in your project:

* `unhook.yaml` or `unhook.yml` in the project root
* Custom path via the plugin settings

Example `unhook.yaml`:

```yaml theme={null}
version: 1
apiKey: your-api-key-here
delivery:
  destinations:
    - name: local
      url: http://localhost:3000/webhook
      ping: true
```

### 3. Start Receiving Webhooks

Once authenticated and configured:

1. **Create a webhook URL** at [unhook.sh/app](https://unhook.sh/app)
2. **Configure your webhook provider** (Stripe, GitHub, etc.) to use the Unhook URL
3. **View events in your IDE** - Events will appear in the Unhook tool window as they're received

## Core Features

### Tool Window Interface

The main interface for webhook management:

* **Events Table**: Displays events with columns for time, provider, event type, method, status, and response time
* **Event Details Panel**: Shows detailed information when an event is selected
* **Toolbar Actions**: Quick access to refresh, clear, and settings
* **Status Display**: Connection status and active session information

#### Event Actions

Each event supports these actions:

* **View Event** - Select event to see details in the lower panel
* **Replay Event** - Right-click and select "Replay Event" to resend
* **Copy Event** - Right-click and select "Copy Event" to copy JSON to clipboard

### Event Details Panel

Comprehensive view for inspecting webhook data:

* **Event Information**: ID, timestamp, provider, and event type
* **Request Details**: Method, URL, headers, and body
* **Response Data**: Status code and response timing
* **Headers View**: Expandable view of all request headers
* **Body Formatting**: Syntax-highlighted JSON and other formats

### Status Bar Integration

The status bar shows your current Unhook connection status:

* **Unhook: Sign In Required** - Not authenticated (click to sign in)
* **Unhook: Disconnected** - Not connected to service
* **Unhook: Active** - Connected and forwarding events
* **Unhook: Paused** - Connected but event forwarding is disabled

### Menu Integration

Access Unhook features from the main menu:

**Tools → Unhook**

* **Show Events** - Open the tool window
* **Toggle Event Forwarding** - Enable/disable webhook forwarding
* **Sign In** - Authenticate with Unhook
* **Sign Out** - Sign out of Unhook
* **Clear Events** - Clear event history
* **Refresh Events** - Refresh the event list

## Configuration

### Plugin Settings

Configure the plugin through IDE settings:

1. Go to **File → Settings → Tools → Unhook** (or **IntelliJ IDEA → Preferences → Tools → Unhook** on macOS)

#### Available Settings

**General Settings**

* **Enable webhook event forwarding** - Control whether events are forwarded to local endpoints
* **Show notifications for new events** - Display IDE notifications when events arrive
* **Automatically show output panel** - Auto-open output when events are received

**Event Management**

* **Max event history** - Maximum number of events to keep (default: 100)
* **Poll interval (ms)** - How often to check for new events (default: 2000ms)

**Advanced Settings**

* **API URL** - Custom API URL for self-hosted instances

### Project Configuration

The plugin integrates with your existing Unhook configuration:

```yaml theme={null}
# unhook.yaml
version: 1
apiKey: your-api-key

delivery:
  destinations:
    - name: local-dev
      url: http://localhost:3000/webhooks
      ping: true
      headers:
        Authorization: Bearer dev-token
    
    - name: staging
      url: https://staging.example.com/webhooks
      ping: false

destination:
  port: 3001
  path: /webhook
```

## Advanced Usage

### Team Collaboration

When working with a team:

1. **Shared Configuration** - Use a shared `unhook.yaml` in your repository
2. **Individual API Keys** - Each team member uses their own API key
3. **Environment-Specific Destinations** - Configure different endpoints per developer

### Provider Integration

The plugin works with all supported webhook providers:

* **Stripe** - Payment and subscription webhooks
* **GitHub** - Repository and organization events
* **Clerk** - Authentication and user management events
* **Discord** - Bot and server events
* **Custom Providers** - Any webhook-enabled service

### Debugging Workflows

Common debugging patterns:

1. **Event Inspection** - Use the details panel to examine request/response data
2. **Selective Replay** - Replay specific events for testing
3. **Local Testing** - Route webhooks to different local endpoints
4. **Response Analysis** - Check response codes and timing information

### Keyboard Shortcuts

While there are no default keyboard shortcuts, you can set custom ones:

1. Go to **File → Settings → Keymap** (or **IntelliJ IDEA → Preferences → Keymap** on macOS)
2. Search for "Unhook"
3. Assign shortcuts to frequently used actions

Recommended shortcuts:

* **Show Events**: `Ctrl+Shift+U` / `Cmd+Shift+U`
* **Refresh Events**: `Ctrl+Shift+R` / `Cmd+Shift+R`
* **Toggle Delivery**: `Ctrl+Shift+D` / `Cmd+Shift+D`

## Troubleshooting

### Common Issues

#### Authentication Problems

**Issue**: "Failed to authenticate with Unhook"

* **Solution**: Sign out and sign in again using **Tools → Unhook → Sign Out**, then **Sign In**
* **Check**: Ensure you have a valid Unhook account at [unhook.sh](https://unhook.sh)

#### No Events Appearing

**Issue**: Events not showing in the tool window

* **Check**: Verify your `unhook.yaml` configuration is correct
* **Check**: Ensure the webhook URL is properly configured with your provider
* **Solution**: Use the refresh button in the tool window toolbar

#### Configuration Not Found

**Issue**: "No config loaded" error

* **Check**: Ensure `unhook.yaml` exists in your project root
* **Alternative**: Set custom path via plugin settings
* **Verify**: Check YAML syntax is valid

#### Replay Failures

**Issue**: Event replay not working

* **Check**: Ensure delivery is not paused (use **Tools → Unhook → Toggle Event Forwarding**)
* **Check**: Verify destination URLs are accessible
* **Debug**: Check IDE logs for error messages

#### Tool Window Not Visible

**Issue**: Can't find the Unhook tool window

* **Solution**: Go to **View → Tool Windows → Unhook**
* **Alternative**: Right-click on the tool window bar and select **Unhook**

### Debug Information

Access debug information through:

1. **IDE Logs**: **Help → Show Log in Files** (or **Help → Show Log in Finder** on macOS)
2. **Plugin Status**: Check status bar for connection information
3. **Event Details**: Use the details panel to inspect individual events

### Getting Help

* **Documentation**: [unhook.sh/docs](https://unhook.sh/docs)
* **GitHub Issues**: [github.com/unhook-sh/unhook/issues](https://github.com/unhook-sh/unhook/issues)
* **Discord Community**: [discord.gg/qRZzTCK6MZ](https://discord.gg/qRZzTCK6MZ)
* **Email Support**: [chris.watts.t@gmail.com](mailto:chris.watts.t@gmail.com)

## Development & Contributing

### Building from Source

```bash theme={null}
# Clone the repository
git clone https://github.com/unhook-sh/unhook.git
cd unhook/apps/jetbrains-extension

# Build the plugin
./gradlew build

# Run IDE with plugin for testing
./gradlew runIde

# Build distribution
./gradlew buildPlugin
```

### Development Mode

```bash theme={null}
# Start development with auto-reload
./gradlew runIde

# Build and verify plugin
./gradlew verifyPlugin
```

### Contributing

We welcome contributions! See our [Contributing Guide](https://github.com/unhook-sh/unhook/blob/main/CONTRIBUTING.md) for details.

## Changelog

See the [full changelog](https://github.com/unhook-sh/unhook/blob/main/apps/jetbrains-extension/CHANGELOG.md) for all updates and improvements.

## License

The Unhook JetBrains Plugin is open source software licensed under the MIT License.


# JetBrains Extension Release Automation
Source: https://docs.unhook.sh/jetbrains-extension-automation

Automated release system for the JetBrains plugin

# JetBrains Extension Release Automation

This document outlines the automated release system for the JetBrains plugin (`apps/jetbrains-extension`) that enables seamless publishing to the JetBrains Marketplace with optional code signing.

## Implementation Overview

The automation consists of two main components:

### 1. GitHub Workflow

The workflow is defined in `.github/workflows/jetbrains-extension-release.yml`:

**Triggers:**

* Automatically after the "NPM Release" workflow completes
* Manual dispatch for testing/emergency releases

**Conditions:**

* Only runs when the commit message contains "chore: version packages" (indicating a version bump)
* Only runs when the JetBrains extension's `package.json` version was actually changed

**Process:**

1. **Version Check**: Validates that this is a version bump commit and that the JetBrains extension version specifically changed
2. **Release**: Builds, verifies, signs (optionally), publishes to JetBrains Marketplace, and creates GitHub release

### 2. Composite Action

The composite action is located at `tooling/github/jetbrains-extension/github-release/action.yml`:

**Steps:**

1. **Setup Environment**: Uses the shared setup action and configures Java 21
2. **Setup Gradle**: Configures Gradle with wrapper validation
3. **Build Plugin**: Compiles the Kotlin/Java plugin code
4. **Verify Plugin**: Runs JetBrains plugin verification for compatibility
5. **Sign Plugin**: (Optional) Signs the plugin with provided certificate
6. **Build Distribution**: Creates the final plugin ZIP distribution
7. **Publish to JetBrains Marketplace**: Publishes using Gradle IntelliJ Platform Plugin
8. **Extract Changelog**: Reads version-specific changes from `CHANGELOG.md`
9. **Create GitHub Release**: Creates release with tag `jetbrains-v{version}` and attaches ZIP file

## Setup Requirements

### Required GitHub Secrets

Add the following secrets to your GitHub repository:

* `JETBRAINS_MARKETPLACE_TOKEN`: Token for JetBrains Marketplace
  * Generate at: [https://plugins.jetbrains.com/author/me/tokens](https://plugins.jetbrains.com/author/me/tokens)
  * Requires publishing permissions
  * Should be associated with your JetBrains account

### Optional GitHub Secrets (Recommended for Production)

* `JETBRAINS_CERTIFICATE_CHAIN`: Certificate chain for plugin signing
  * Should be in PEM format
  * Remove line breaks and store as single-line string
  * Enhances trust and security for plugin distribution

* `JETBRAINS_PRIVATE_KEY`: Private key for plugin signing
  * Should be in PEM format
  * Remove line breaks and store as single-line string
  * Must match the certificate chain

* `JETBRAINS_PRIVATE_KEY_PASSWORD`: Password for private key (if encrypted)
  * Only required if your private key is password-protected

### JetBrains Marketplace Setup

Before publishing to JetBrains Marketplace:

1. **Create JetBrains account** at jetbrains.com
2. **Apply for publisher status** at plugins.jetbrains.com
3. **Create API token** in your publisher profile
4. **Plugin verification** is handled automatically by the workflow

<Note>
  The automation will handle plugin verification and compatibility checks automatically during the build process.
</Note>

### JetBrains Plugin Configuration

The automation expects:

* Plugin built with Gradle and IntelliJ Platform Gradle Plugin (already configured)
* Plugin ID set to "sh.unhook.jetbrains" in `plugin.xml` (already set)
* Changelog maintained in `apps/jetbrains-extension/CHANGELOG.md` with version sections like:

```markdown theme={null}
## [0.2.4] - 2024-01-15
- Feature description
- Bug fix description

## [0.2.3] - 2024-01-10
- Previous version changes
```

## Workflow Integration

### Automatic Process

1. **NPM Release**: Maintainer triggers NPM Release workflow (manually or via GitHub Actions)
2. **Version Bump**: Release script bumps versions and generates AI-powered changelog
3. **JetBrains Release**: If JetBrains extension version changed, the JetBrains Extension Release workflow automatically triggers
4. **Build & Verification**: Plugin is built and verified for compatibility
5. **Optional Signing**: If certificates are configured, plugin is signed for enhanced trust
6. **Marketplace Publication**: Plugin is published to JetBrains Marketplace
7. **GitHub Release**: Release created with ZIP file attachment

### Manual Fallback

If automation fails, manual release steps:

```bash theme={null}
# Navigate to extension directory
cd apps/jetbrains-extension

# Build plugin
./gradlew build

# Verify plugin
./gradlew verifyPlugin

# Build distribution
./gradlew buildPlugin

# Publish to JetBrains Marketplace (requires JETBRAINS_MARKETPLACE_TOKEN)
./gradlew publishPlugin
```

## Platform Coverage

Publishing to JetBrains Marketplace ensures broad compatibility across all JetBrains IDEs:

* **IntelliJ IDEA** (Community & Ultimate)
* **WebStorm, PhpStorm, PyCharm** (Professional & Community)
* **RubyMine, CLion, GoLand**
* **DataGrip, Rider**
* **Android Studio** (Google's distribution)

## Plugin Verification

The workflow includes comprehensive verification:

* **Compatibility Check**: Ensures plugin works with target IDE versions (2024.2+)
* **API Usage Validation**: Detects deprecated or internal API usage
* **Plugin Structure**: Validates plugin.xml and overall plugin structure
* **Dependency Analysis**: Checks for missing or conflicting dependencies
* **Build Integrity**: Verifies successful compilation and packaging

## Code Signing (Optional)

The workflow supports optional plugin signing for enhanced security:

### Benefits of Signing

* **Enhanced Trust**: Signed plugins are marked as verified
* **Security**: Prevents tampering and ensures authenticity
* **Professional Distribution**: Recommended for commercial plugins

### Certificate Requirements

* **Code Signing Certificate**: From a trusted Certificate Authority
* **PEM Format**: Certificate chain and private key in PEM format
* **Key Management**: Secure storage in GitHub Secrets

### Signing Process

1. **Certificate Validation**: Verifies certificate chain integrity
2. **Plugin Signing**: Signs the compiled plugin with private key
3. **Verification**: Confirms signature validity
4. **Distribution**: Signed plugin ready for marketplace

## Monitoring

The workflow provides clear logging for each step:

* Build status and compilation output
* Plugin verification results with detailed reports
* Signing status (if configured)
* JetBrains Marketplace publishing result
* GitHub release creation

Failed steps will be clearly indicated in the GitHub Actions logs with actionable error messages.

## Security Considerations

* `JETBRAINS_MARKETPLACE_TOKEN` is securely stored as GitHub secret
* Certificate and private key are encrypted in GitHub Secrets
* Signing certificates have minimal required permissions (code signing only)
* Plugin files are built from source during workflow execution
* All steps logged for audit trail
* No sensitive data exposed in logs

## File Structure

```
.github/workflows/
└── jetbrains-extension-release.yml

tooling/github/jetbrains-extension/
└── github-release/
    └── action.yml

apps/jetbrains-extension/
├── build.gradle.kts
├── gradle.properties
├── src/main/resources/META-INF/plugin.xml
└── CHANGELOG.md
```

<Note>
  The workflow only triggers when the JetBrains extension version specifically changes. GitHub releases use the tag format `jetbrains-v{version}` to distinguish from other extension releases.
</Note>

## Best Practices

### Version Management

* ZIP files are automatically attached to GitHub releases for manual distribution
* Version management is handled by the NPM Release workflow with AI-powered changelog generation
* Semantic versioning is enforced through the release script

### Quality Assurance

* Plugin verification runs before publishing to catch compatibility issues
* Build artifacts include verification reports for debugging
* Automated testing ensures plugin stability across IDE versions

### Security

* Code signing enhances plugin trustworthiness
* Secure token management through GitHub Secrets
* Certificate validation prevents distribution of compromised plugins

### Development Workflow

* The automation follows the same patterns as other release workflows for consistency
* Gradle-based build system provides reliable, reproducible builds
* Local development workflow mirrors CI/CD process

## Build Artifacts

Each successful build produces:

### Distribution Files

* **Plugin ZIP**: Ready for marketplace or manual installation
* **Build Reports**: Compilation and verification results
* **Verification Report**: Compatibility analysis

### GitHub Release Assets

* **unhook-jetbrains-.zip**: Main plugin distribution
* **Build artifacts**: Uploaded for 30 days for debugging

### Marketplace Distribution

* **Automatic Publication**: Direct upload to JetBrains Marketplace
* **Version Metadata**: Changelog and compatibility information
* **Plugin Verification**: Marketplace runs additional checks

This automation provides a production-ready, secure release pipeline that ensures high-quality plugin distribution while maintaining security and reliability standards.


# MCP Integration
Source: https://docs.unhook.sh/mcp-integration

Use AI assistants to debug webhooks with Model Context Protocol

# Unhook MCP Server

Use Unhook's webhook data through the Model Context Protocol

A Model Context Protocol (MCP) server implementation that integrates Unhook for webhook debugging and analysis capabilities. Our MCP server provides access to your webhook events, requests, and analytics through AI assistants like Claude and Cursor.

## Features

* Webhook event monitoring and analysis
* Request inspection and debugging
* Performance metrics and failure analysis
* Real-time webhook data access
* Cloud and self-hosted support
* SSE transport support

## Installation

You can either use our remote hosted URL or run the server locally. Get your API key from your Unhook dashboard at [https://unhook.sh/app/api-keys](https://unhook.sh/app/api-keys).

### Remote hosted URL

```json theme={null}
https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse
```

### Running with npx

```bash theme={null}
env UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server
```

### Manual Installation

```bash theme={null}
npm install -g @unhook/mcp-server
```

> Try out our MCP Server on MCP.so's playground or integrate with your favorite AI assistant.

## Configuration

### Environment Variables

#### Required for Cloud API

* `UNHOOK_API_KEY`: Your Unhook API key
  * Required when using cloud API (default)
  * Get this from [https://unhook.sh/app/api-keys](https://unhook.sh/app/api-keys)
* `UNHOOK_API_URL` (Optional): Custom API endpoint for self-hosted instances
  * Example: `https://api.your-domain.com`
  * If not provided, the cloud API will be used (requires API key)

#### Optional Configuration

##### Retry Configuration

* `UNHOOK_RETRY_MAX_ATTEMPTS`: Maximum number of retry attempts (default: 3)
* `UNHOOK_RETRY_INITIAL_DELAY`: Initial delay in milliseconds before first retry (default: 1000)
* `UNHOOK_RETRY_MAX_DELAY`: Maximum delay in milliseconds between retries (default: 10000)
* `UNHOOK_RETRY_BACKOFF_FACTOR`: Exponential backoff multiplier (default: 2)

##### Rate Limiting

* `UNHOOK_RATE_LIMIT_REQUESTS`: Maximum requests per minute (default: 60)
* `UNHOOK_RATE_LIMIT_WINDOW`: Rate limit window in milliseconds (default: 60000)

### Configuration Examples

#### Basic Cloud Configuration

```json theme={null}
{
  "mcpServers": {
    "unhook": {
      "url": "https://unhook.sh/api/mcp/YOUR_API_KEY/sse",
      "transport": "sse"
    }
  }
}
```

#### Self-Hosted Configuration

```json theme={null}
{
  "mcpServers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "your-api-key",
        "UNHOOK_API_URL": "https://api.your-domain.com"
      }
    }
  }
}
```

## Running on Different Platforms

### Running on Cursor

Add Unhook MCP server to Cursor

#### Manual Installation

**Note**: Requires Cursor version 0.45.6+

To configure Unhook MCP in Cursor **v0.48.6**:

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add new global MCP server"
4. Enter the following code:

```json theme={null}
{
  "mcpServers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}
```

To configure Unhook MCP in Cursor **v0.45.6**:

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following:
   * Name: "unhook" (or your preferred name)
   * Type: "command"
   * Command: `env UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server`

> If you are using Windows and are running into issues, try `cmd /c "set UNHOOK_API_KEY=your-api-key && npx -y @unhook/mcp-server"`

Replace `your-api-key` with your Unhook API key. If you don't have one yet, you can get it from [https://unhook.sh/app/api-keys](https://unhook.sh/app/api-keys).

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Unhook MCP when appropriate, but you can explicitly request it by describing your webhook debugging needs.

### Running on Windsurf

Add this to your `./codeium/windsurf/model_config.json`:

```json theme={null}
{
  "mcpServers": {
    "mcp-server-unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Running with SSE Mode

To run the server using Server-Sent Events (SSE) locally instead of the default stdio transport:

```bash theme={null}
env SSE_LOCAL=true UNHOOK_API_KEY=your-api-key npx -y @unhook/mcp-server
```

Use the url: `http://localhost:3000/sse` or `https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse`

### Running on VS Code

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.

```json theme={null}
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Unhook API Key",
        "password": true
      }
    ],
    "servers": {
      "unhook": {
        "command": "npx",
        "args": ["-y", "@unhook/mcp-server"],
        "env": {
          "UNHOOK_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}
```

Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others:

```json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Unhook API Key",
      "password": true
    }
  ],
  "servers": {
    "unhook": {
      "command": "npx",
      "args": ["-y", "@unhook/mcp-server"],
      "env": {
        "UNHOOK_API_KEY": "${input:apiKey}"
      }
    }
  }
}
```

### Running on Claude Desktop

Add this to the Claude config file:

```json theme={null}
{
  "mcpServers": {
    "unhook": {
      "url": "https://unhook.sh/api/mcp/{YOUR_API_KEY}/sse"
    }
  }
}
```

## Rate Limiting and Performance

The server utilizes Unhook's built-in rate limiting and performance optimization:

* Automatic rate limit handling with exponential backoff
* Efficient data pagination for large datasets
* Smart request caching and deduplication
* Automatic retries for transient errors

## Available Tools

### 1. Search Events Tool (`search_events`)

Search webhook events with advanced filtering options.

```json theme={null}
{
  "name": "search_events",
  "arguments": {
    "webhookId": "wh_123",
    "status": "failed",
    "limit": 50,
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "source": "stripe"
  }
}
```

### 2. Search Requests Tool (`search_requests`)

Search webhook requests with detailed filtering.

```json theme={null}
{
  "name": "search_requests",
  "arguments": {
    "webhookId": "wh_123",
    "status": "failed",
    "limit": 50,
    "minResponseTime": 1000,
    "maxResponseTime": 5000
  }
}
```

### 3. Analyze Event Tool (`analyze_event`)

Get detailed analysis of a specific webhook event.

```json theme={null}
{
  "name": "analyze_event",
  "arguments": {
    "eventId": "evt_123"
  }
}
```

### 4. Analyze Request Tool (`analyze_request`)

Get detailed analysis of a specific webhook request.

```json theme={null}
{
  "name": "analyze_request",
  "arguments": {
    "requestId": "req_123"
  }
}
```

### 5. Get Webhook Stats Tool (`get_webhook_stats`)

Get comprehensive statistics for webhooks.

```json theme={null}
{
  "name": "get_webhook_stats",
  "arguments": {
    "webhookId": "wh_123",
    "timeRange": "24h",
    "includeFailures": true,
    "includePerformance": true
  }
}
```

### 6. Create Test Event Tool (`create_test_event`)

Create a test webhook event for debugging.

```json theme={null}
{
  "name": "create_test_event",
  "arguments": {
    "webhookId": "wh_123",
    "payload": {
      "test": "data",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    "headers": {
      "Content-Type": "application/json",
      "X-Test-Header": "test-value"
    }
  }
}
```

### 7. Debug Webhook Issue Tool (`debug_webhook_issue`)

Get intelligent debugging assistance for webhook issues.

```json theme={null}
{
  "name": "debug_webhook_issue",
  "arguments": {
    "webhookId": "wh_123",
    "issueType": "failures",
    "timeRange": "1h",
    "includeRecommendations": true
  }
}
```

### 8. Performance Report Tool (`performance_report`)

Generate comprehensive performance reports.

```json theme={null}
{
  "name": "performance_report",
  "arguments": {
    "webhookIds": ["wh_123", "wh_456"],
    "timeRange": "7d",
    "includeTrends": true,
    "includeRecommendations": true
  }
}
```

## Available Resources

### Recent Events (`webhook://events/recent`)

Access the most recent webhook events with metadata.

### Recent Requests (`webhook://requests/recent`)

Access the most recent webhook requests with response data.

### Webhook List (`webhook://webhooks/list`)

Get all configured webhooks in your organization.

### Active Connections (`webhook://connections/active`)

View currently active webhook connections.

### Statistics Overview (`webhook://stats/overview`)

Get high-level statistics for all webhooks.

## Logging System

The server includes comprehensive logging:

* Connection status and authentication
* Request/response performance metrics
* Error conditions and retry attempts
* Rate limit tracking

Example log messages:

```
[INFO] Unhook MCP Server initialized successfully
[INFO] Connected to webhook wh_123
[INFO] Retrieved 50 events for analysis
[WARNING] Rate limit approaching, throttling requests
[ERROR] Authentication failed, retrying in 2s...
```

## Error Handling

The server provides robust error handling:

* Automatic retries for transient errors
* Rate limit handling with backoff
* Detailed error messages with context
* Authentication error recovery
* Network resilience

Example error response:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}
```

## Usage Examples

### Debugging Failed Webhooks

Ask your AI assistant:

* "Show me all failed webhook events from the last hour"
* "Why are my Stripe webhooks failing?"
* "Analyze the error patterns in my webhook requests"

### Performance Analysis

Ask your AI assistant:

* "What's the average response time for my webhooks?"
* "Which webhooks have the highest failure rate?"
* "Generate a performance report for my payment webhooks"

### Request Inspection

Ask your AI assistant:

* "Show me the payload for event evt\_123"
* "What headers were sent with the last GitHub webhook?"
* "Compare successful vs failed requests for my Clerk webhook"

## Security

### Authentication

* All MCP requests require authentication via your Unhook API key
* API keys are scoped to your organization's data only
* Never share your API key publicly

### Data Access

* MCP servers can only access data you have permission to view
* All data transmission is encrypted over HTTPS
* No webhook data is stored by the AI assistant

### Best Practices

* Use environment-specific API keys for development vs production
* Rotate your API keys regularly
* Review MCP access logs in your dashboard

## Troubleshooting

### Connection Issues

<AccordionGroup>
  <Accordion title="AI assistant can't connect to Unhook">
    1. Verify your configuration file syntax is valid JSON
    2. Check that your API key is correct and not expired
    3. Ensure you're using HTTPS (not HTTP) in the URL
    4. Restart your AI assistant after configuration changes
  </Accordion>

  <Accordion title="No webhook data appearing">
    1. Confirm you have webhooks configured in your dashboard
    2. Check that your API key has the correct permissions
    3. Verify you're in the right organization
    4. Try manually triggering a webhook to generate data
  </Accordion>

  <Accordion title="Authentication errors">
    1. Regenerate your API key in the dashboard
    2. Ensure the API key is properly formatted in the configuration
    3. Check for extra spaces or characters in the API key
    4. Verify the API key hasn't expired
  </Accordion>

  <Accordion title="Rate limiting issues">
    1. Check your current rate limits in the dashboard
    2. Reduce the frequency of requests
    3. Use pagination to limit data size
    4. Contact support if you need higher limits
  </Accordion>
</AccordionGroup>

### Performance

<Note>
  The MCP server limits responses to prevent overwhelming AI assistants:

  * Events: Maximum 100 per request
  * Requests: Maximum 100 per request
  * Use search filters to find specific data
  * Enable pagination for large datasets
</Note>

## Development

```bash theme={null}
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test
```

### Contributing

1. Fork the repository
2. Create your feature branch
3. Run tests: `npm test`
4. Submit a pull request

## Support

Need help with MCP integration?

* Check our [GitHub discussions](https://github.com/unhook-sh/unhook/discussions)
* Join our [Discord community](https://discord.gg/qRZzTCK6MZ)
* Email support at [support@unhook.sh](mailto:support@unhook.sh)

## License

MIT License - see LICENSE file for details


# Webhook Providers
Source: https://docs.unhook.sh/providers

Connect Unhook with popular webhook providers

# Webhook Provider Integration Guides

Unhook makes it easy to receive webhooks from any provider. Each provider has specific configuration requirements and webhook event types. Select your provider below for detailed setup instructions.

## Popular Providers

<CardGroup>
  <Card title="Stripe" icon="stripe" href="/providers/stripe">
    Payment processing and subscription webhooks
  </Card>

  <Card title="GitHub" icon="github" href="/providers/github">
    Repository and workflow events
  </Card>

  <Card title="Clerk" icon="user-shield" href="/providers/clerk">
    User authentication and management
  </Card>

  <Card title="Twilio" icon="comment-sms" href="/providers/twilio">
    SMS, voice, and communication events
  </Card>

  <Card title="SendGrid" icon="envelope" href="/providers/sendgrid">
    Email delivery and engagement tracking
  </Card>

  <Card title="Shopify" icon="cart-shopping" href="/providers/shopify">
    E-commerce and order webhooks
  </Card>
</CardGroup>

## Payment & Commerce

<CardGroup>
  <Card title="PayPal" href="/providers/paypal">Payment notifications</Card>
  <Card title="Square" href="/providers/square">Payment and POS events</Card>
  <Card title="Braintree" href="/providers/braintree">Payment gateway webhooks</Card>
  <Card title="Paddle" href="/providers/paddle">SaaS billing events</Card>
  <Card title="Chargebee" href="/providers/chargebee">Subscription management</Card>
  <Card title="Recurly" href="/providers/recurly">Recurring billing webhooks</Card>
</CardGroup>

## Communication & Collaboration

<CardGroup>
  <Card title="Slack" href="/providers/slack">Team messaging events</Card>
  <Card title="Discord" href="/providers/discord">Community platform webhooks</Card>
  <Card title="Microsoft Teams" href="/providers/microsoft-teams">Enterprise communication</Card>
  <Card title="Zoom" href="/providers/zoom">Video conferencing events</Card>
  <Card title="Intercom" href="/providers/intercom">Customer messaging</Card>
  <Card title="Mailchimp" href="/providers/mailchimp">Email marketing events</Card>
</CardGroup>

## Development & Infrastructure

<CardGroup>
  <Card title="Vercel" href="/providers/vercel">Deployment notifications</Card>
  <Card title="Netlify" href="/providers/netlify">Build and deploy events</Card>
  <Card title="CircleCI" href="/providers/circleci">CI/CD pipeline webhooks</Card>
  <Card title="PagerDuty" href="/providers/pagerduty">Incident management</Card>
  <Card title="Sentry" href="/providers/sentry">Error tracking alerts</Card>
  <Card title="Datadog" href="/providers/datadog">Monitoring and analytics</Card>
</CardGroup>

## Project Management

<CardGroup>
  <Card title="Linear" href="/providers/linear">Issue tracking</Card>
  <Card title="Jira" href="/providers/jira">Agile project management</Card>
  <Card title="Notion" href="/providers/notion">Workspace notifications</Card>
  <Card title="Asana" href="/providers/asana">Task management</Card>
  <Card title="Monday.com" href="/providers/monday">Work OS events</Card>
  <Card title="ClickUp" href="/providers/clickup">Productivity platform</Card>
</CardGroup>

## Authentication & Security

<CardGroup>
  <Card title="Auth0" href="/providers/auth0">Identity management</Card>
  <Card title="Okta" href="/providers/okta">Enterprise authentication</Card>
  <Card title="Firebase" href="/providers/firebase">Authentication events</Card>
  <Card title="Supabase" href="/providers/supabase">Backend platform webhooks</Card>
  <Card title="WorkOS" href="/providers/workos">Enterprise SSO</Card>
  <Card title="FusionAuth" href="/providers/fusionauth">Customer identity</Card>
</CardGroup>

## Form & Survey

<CardGroup>
  <Card title="Typeform" href="/providers/typeform">Form submissions</Card>
  <Card title="Google Forms" href="/providers/google-forms">Survey responses</Card>
  <Card title="JotForm" href="/providers/jotform">Form builder webhooks</Card>
  <Card title="SurveyMonkey" href="/providers/surveymonkey">Survey platform</Card>
  <Card title="Calendly" href="/providers/calendly">Scheduling events</Card>
  <Card title="Cal.com" href="/providers/cal">Open-source scheduling</Card>
</CardGroup>

## Storage & Files

<CardGroup>
  <Card title="Box" href="/providers/box">File collaboration</Card>
  <Card title="Dropbox" href="/providers/dropbox">Cloud storage events</Card>
  <Card title="Google Drive" href="/providers/google-drive">Document notifications</Card>
  <Card title="OneDrive" href="/providers/onedrive">Microsoft cloud storage</Card>
  <Card title="AWS S3" href="/providers/aws-s3">Object storage events</Card>
  <Card title="Cloudinary" href="/providers/cloudinary">Media management</Card>
</CardGroup>

## Analytics & Marketing

<CardGroup>
  <Card title="Segment" href="/providers/segment">Customer data events</Card>
  <Card title="Mixpanel" href="/providers/mixpanel">Product analytics</Card>
  <Card title="Amplitude" href="/providers/amplitude">Digital analytics</Card>
  <Card title="HubSpot" href="/providers/hubspot">CRM and marketing</Card>
  <Card title="Salesforce" href="/providers/salesforce">Enterprise CRM</Card>
  <Card title="Pipedrive" href="/providers/pipedrive">Sales CRM webhooks</Card>
</CardGroup>

## Social Media

<CardGroup>
  <Card title="Facebook" href="/providers/facebook">Social platform events</Card>
  <Card title="Instagram" href="/providers/instagram">Photo sharing webhooks</Card>
  <Card title="Twitter/X" href="/providers/twitter">Social media events</Card>
  <Card title="LinkedIn" href="/providers/linkedin">Professional network</Card>
  <Card title="TikTok" href="/providers/tiktok">Video platform webhooks</Card>
  <Card title="YouTube" href="/providers/youtube">Video notifications</Card>
</CardGroup>

## Custom Providers

If your provider is not listed above, you can still use Unhook! Simply use your unique Unhook URL as the webhook endpoint. See our [Custom Integration Guide](/providers/custom) for more details.

## Quick Start

1. Choose your provider from the list above
2. Follow the provider-specific setup instructions
3. Copy your Unhook URL: `https://unhook.sh/wh_YOUR_ID`
4. Configure the webhook in your provider's dashboard
5. Start receiving webhooks locally!

## Need Help?

* Check the provider-specific documentation for detailed setup steps
* Join our [Discord community](https://discord.gg/unhook) for support
* Contact us at [support@unhook.sh](mailto:support@unhook.sh)


# Quickstart
Source: https://docs.unhook.sh/quickstart

Get started with Unhook in under 5 minutes

## Choose Your Setup Method

<Tabs>
  <Tab title="VS Code Extension">
    The fastest way to get started with Unhook is using our VS Code extension:

    <Steps>
      <Step title="Install Extension">
        1. Open VS Code
        2. Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)
        3. Search for "Unhook - Webhook Development"
        4. Click **Install**
      </Step>

      <Step title="Authenticate">
        1. Click the Unhook icon in the Activity Bar
        2. Click "Sign in to Unhook" in the status bar
        3. Complete the OAuth flow in your browser
      </Step>

      <Step title="Configure">
        Create an `unhook.yml` file in your workspace:

        ```yaml theme={null}
        webhookUrl: https://unhook.sh/your-org/your-webhook-name
        destination:
          - name: local
            url: http://localhost:3000/api/webhooks
        delivery:
          - source: "*"
            destination: local
        ```
      </Step>

      <Step title="Start Receiving Webhooks">
        1. Create a webhook URL at [unhook.sh/app](https://unhook.sh/app)
        2. Configure your provider to use the Unhook URL
        3. View events in the VS Code sidebar as they arrive
      </Step>
    </Steps>

    <Note>
      The VS Code extension provides a complete webhook development environment with real-time monitoring, request replay, and team collaboration features. [Learn more →](/vscode-extension)
    </Note>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Installation">
        Install Unhook using your preferred package manager:

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

      <Step title="Initialize Project">
        Run the initialization command:

        ```bash theme={null}
        npx @unhook/cli init
        ```

        This will:

        * Open your browser for authentication
        * Create an `unhook.yml` file
        * Configure your webhook endpoints
      </Step>

      <Step title="Start Your Webhook">
        Start the webhook to begin receiving webhooks:

        ```bash theme={null}
        npx @unhook/cli listen
        ```
      </Step>

      <Step title="Configure Your Webhook Provider">
        Set up your webhook provider with the provided Unhook URL:

        ```bash theme={null}
        https://unhook.sh/your-org/your-webhook-name
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Configuration

### Basic Configuration

Create an `unhook.yml` file in your project root:

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

### Environment Variables

Configure via environment variables:

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

1. Go to your [Stripe Dashboard](https://dashboard.stripe.com/webhooks)
2. Click "Add Endpoint"
3. Enter your Unhook URL:

```bash theme={null}
https://unhook.sh/wh_your_webhook_id
```

### GitHub

1. Go to your repository settings
2. Navigate to "Webhooks"
3. Click "Add webhook"
4. Enter your Unhook URL:

```bash theme={null}
https://unhook.sh/wh_your_webhook_id
```

### Clerk

1. Go to your [Clerk Dashboard](https://dashboard.clerk.dev)
2. Navigate to "Webhooks"
3. Click "Add Endpoint"
4. Enter your Unhook URL:

```bash theme={null}
https://unhook.sh/your-org/your-webhook-name
```

## Team Development

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

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

```bash theme={null}
rm ~/.unhook/auth-storage.json
```

## Next Steps

<CardGroup>
  <Card title="VS Code Extension" icon="code" href="/vscode-extension">
    Complete webhook development environment in VS Code
  </Card>

  <Card title="Team Setup" icon="users" href="/team-setup">
    Learn how to configure Unhook for your entire team
  </Card>

  <Card title="Dashboard" icon="gauge" href="/dashboard">
    Monitor and debug your webhooks in real-time
  </Card>

  <Card title="Provider Guides" icon="plug" href="/providers">
    Detailed setup guides for all supported webhook providers
  </Card>
</CardGroup>

## Support

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


# CLI Tool
Source: https://docs.unhook.sh/solutions/cli-tool

Command line interface for local webhook testing and development

# Unhook CLI Tool

The Unhook CLI is a powerful command-line interface that enables developers to test webhooks locally without exposing their development environment to the internet.

## Overview

The CLI tool provides a seamless way to:

* Create shareable webhook URLs that route to your local environment
* Monitor webhook events in real-time
* Debug webhook payloads and responses
* Collaborate with team members using shared webhook configurations

## Installation

Install the Unhook CLI globally using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @unhook/cli
  ```

  ```bash yarn theme={null}
  yarn global add @unhook/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @unhook/cli
  ```

  ```bash bun theme={null}
  bun add -g @unhook/cli
  ```
</CodeGroup>

## Quick Start

1. **Initialize your project**:
   ```bash theme={null}
   npx @unhook/cli init
   ```

2. **Start listening for webhooks**:
   ```bash theme={null}
   unhook listen --port 3000
   ```

3. **Use the generated webhook URL** in your provider's settings:
   ```
   https://unhook.sh/wh_your_webhook_id
   ```

## Core Features

### Local Webhook Routing

The CLI creates a secure tunnel that routes incoming webhooks to your local development server:

```bash theme={null}
# Route webhooks to local port 3000
unhook listen --port 3000

# Route to a specific endpoint
unhook listen --port 3000 --path /api/webhooks

# Route to a remote URL
unhook listen --redirect https://api.example.com/webhooks
```

### Real-time Monitoring

Monitor webhook activity directly in your terminal:

```bash theme={null}
# Enable debug mode for detailed logging
unhook listen --debug

# View webhook statistics
unhook stats

# Check connection status
unhook status
```

### Team Collaboration

Share webhook URLs across your team while maintaining individual environments:

```bash theme={null}
# Use a shared webhook ID
unhook listen --webhook-id team_webhook_id

# Set a unique client ID for team routing
unhook listen --client-id dev1 --webhook-id team_webhook_id
```

## Configuration

### Configuration File

Create an `unhook.yaml` file in your project root:

```yaml theme={null}
webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
debug: false
telemetry: true
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
    ping: true
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "local"
  - source: "github"
    destination: "local"
```

### Environment Variables

All CLI options can be set via environment variables:

```bash theme={null}
# Core settings
WEBHOOK_PORT=3000
WEBHOOK_API_KEY=your_api_key
WEBHOOK_CLIENT_ID=dev-1
WEBHOOK_DEBUG=true

# Advanced settings
WEBHOOK_REDIRECT=https://api.example.com
WEBHOOK_PING=true
```

## Command Reference

### `unhook listen`

Start listening for webhook events.

**Options:**

* `--port, -p`: Local port to deliver requests to
* `--webhook-id, -t`: Webhook ID to use
* `--client-id, -c`: Unique client ID for team routing
* `--redirect, -r`: Redirect URL instead of local port
* `--debug, -d`: Enable debug logging
* `--ping`: Health check configuration

**Examples:**

```bash theme={null}
# Basic usage
unhook listen --port 3000

# With custom client ID
unhook listen --client-id dev-1 --port 3000

# Redirect to remote URL
unhook listen --redirect https://api.example.com/webhooks
```

### `unhook init`

Initialize a new Unhook project.

**Examples:**

```bash theme={null}
# Initialize with default settings
npx @unhook/cli init

# Initialize with specific webhook ID
npx @unhook/cli init --webhook-id wh_123
```

### `unhook status`

Check the status of your webhook connection.

**Examples:**

```bash theme={null}
# Check current status
unhook status

# Check with verbose output
unhook status --verbose
```

## Advanced Features

### Health Checks

Configure health checks for your endpoints:

```yaml theme={null}
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
    ping: true  # Enable default health check
  - name: "custom"
    url: "http://localhost:3001/api/webhooks"
    ping: "http://localhost:3001/health"  # Custom health check URL
```

### Multiple Destinations

Route different webhook types to different endpoints:

```yaml theme={null}
destination:
  - name: "stripe-endpoint"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-endpoint"
    url: "http://localhost:3000/api/webhooks/github"
delivery:
  - source: "stripe"
    destination: "stripe-endpoint"
  - source: "github"
    destination: "github-endpoint"
```

### Authentication

Configure API key authentication for private webhooks:

```yaml theme={null}
webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
apiKey: "your_api_key"  # Required for private webhooks
destination:
  - name: "secure-endpoint"
    url: "http://localhost:3000/api/webhooks"
```

## Integration Examples

### Stripe Webhooks

```bash theme={null}
# Start listening for Stripe webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-stripe-webhook

# Configure in Stripe dashboard
# Webhook URL: https://unhook.sh/your-org/your-stripe-webhook
```

### GitHub Webhooks

```bash theme={null}
# Start listening for GitHub webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-github-webhook

# Configure in GitHub repository settings
# Webhook URL: https://unhook.sh/your-org/your-github-webhook
```

### Clerk Authentication

```bash theme={null}
# Start listening for Clerk webhooks
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-clerk-webhook

# Configure in Clerk dashboard
# Webhook URL: https://unhook.sh/your-org/your-clerk-webhook
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Connection Issues">
    * Check your internet connection
    * Verify the webhook ID is correct
    * Ensure the port is available and not blocked by firewall
  </Accordion>

  <Accordion title="Authentication Problems">
    * Clear auth data: `rm ~/.unhook/auth-storage.json`
    * Re-run initialization: `npx @unhook/cli init`
    * Verify API key is correct
  </Accordion>

  <Accordion title="Webhook Not Receiving Events">
    * Check webhook URL is correctly configured in provider dashboard
    * Verify webhook is active in Unhook dashboard
    * Enable debug mode: `unhook listen --debug`
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug logging for detailed troubleshooting:

```bash theme={null}
# Enable debug mode
unhook listen --debug

# View debug information in real-time
# Check connection status, webhook events, and error messages
```

## Best Practices

1. **Use Client IDs**: Always specify a meaningful client ID in team environments
2. **Enable Health Checks**: Configure health checks for all endpoints
3. **Use Configuration Files**: Keep settings in version control for team consistency
4. **Monitor Logs**: Use debug mode when troubleshooting issues
5. **Secure API Keys**: Store sensitive information in environment variables

## Next Steps

* [VS Code Extension](/solutions/vscode-extension) - Monitor webhooks in your editor
* [Team Collaboration](/solutions/team-collaboration) - Share webhooks with your team
* [Provider Integrations](/solutions/provider-integrations) - Connect with popular services
* [Security Features](/solutions/security) - Learn about data protection


# JetBrains Plugin
Source: https://docs.unhook.sh/solutions/jetbrains-plugin

Monitor and debug webhooks in JetBrains IDEs

# JetBrains Plugin

The Unhook JetBrains plugin brings powerful webhook monitoring and debugging capabilities to all JetBrains IDEs, including IntelliJ IDEA, WebStorm, PyCharm, and more.

## Overview

The JetBrains plugin provides:

* Real-time webhook event monitoring within your IDE
* Webhook payload inspection and debugging
* Event replay functionality for testing
* Team collaboration features
* Seamless integration with your development workflow

## Supported IDEs

The Unhook plugin works with all JetBrains IDEs:

<CardGroup>
  <Card title="IntelliJ IDEA" icon="intellij">
    Ultimate and Community editions
  </Card>

  <Card title="WebStorm" icon="webstorm">
    JavaScript and TypeScript development
  </Card>

  <Card title="PyCharm" icon="pycharm">
    Python development (Professional and Community)
  </Card>

  <Card title="PhpStorm" icon="phpstorm">
    PHP development
  </Card>

  <Card title="GoLand" icon="goland">
    Go development
  </Card>

  <Card title="Rider" icon="rider">
    .NET development
  </Card>
</CardGroup>

## Installation

### From JetBrains Marketplace

1. **Open your JetBrains IDE**
2. **Go to Settings/Preferences** (Ctrl+Alt+S / Cmd+,)
3. **Navigate to Plugins**
4. **Search for "Unhook"**
5. **Click Install**

### From Plugin Repository

1. **Download the plugin** from [JetBrains Plugin Repository](https://plugins.jetbrains.com/plugin/24002-unhook)
2. **Install from disk** in your IDE's plugin settings
3. **Restart your IDE**

## Quick Start

1. **Sign in to Unhook**:
   * Open the Unhook tool window (View → Tool Windows → Unhook)
   * Click "Sign In" and follow the authentication flow

2. **View webhook events**:
   * The Unhook tool window shows real-time webhook events
   * Events are automatically updated as they arrive

3. **Inspect and replay events**:
   * Click on any event to view detailed information
   * Use the "Replay" button to resend webhooks to your local server

## Features

### Real-time Webhook Monitoring

Monitor webhook events directly in your IDE:

<CardGroup>
  <Card title="Live Event Feed" icon="radio">
    See webhook events as they arrive from providers
  </Card>

  <Card title="Event Details" icon="search">
    Inspect headers, payloads, and response data
  </Card>

  <Card title="Status Tracking" icon="check-circle">
    Track success/failure status and response times
  </Card>

  <Card title="Provider Filtering" icon="filter">
    Filter events by provider (Stripe, GitHub, Clerk, etc.)
  </Card>
</CardGroup>

### Webhook Event Inspection

Dive deep into webhook data with comprehensive inspection tools:

```json theme={null}
{
  "event": {
    "id": "evt_1234567890",
    "provider": "stripe",
    "type": "payment_intent.succeeded",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "status": "success"
  },
  "request": {
    "method": "POST",
    "url": "https://unhook.sh/wh_stripe_prod",
    "headers": {
      "content-type": "application/json",
      "stripe-signature": "..."
    },
    "body": {
      "id": "pi_123",
      "object": "payment_intent",
      "amount": 1000,
      "currency": "usd"
    }
  },
  "response": {
    "status": 200,
    "headers": {...},
    "body": {...},
    "duration": 245
  }
}
```

### Event Replay

Test your webhook handlers by replaying events:

1. **Select an event** from the event list
2. **Click "Replay Event"** button
3. **Monitor the response** in real-time
4. **Debug any issues** with your webhook handler

### Team Collaboration

Work seamlessly with your team on webhook development:

* **Shared webhook URLs**: Use the same webhook URL across your team
* **Real-time updates**: See when team members are active
* **Event sharing**: Share specific events with team members for debugging

## Configuration

### Project Configuration

Create an `unhook.yaml` file in your project root:

```yaml theme={null}
webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
server:
  apiUrl: "https://app.unhook.sh"
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
delivery:
  - destination: "local"
```

### Plugin Settings

Configure the plugin through IDE settings:

1. **Open Settings/Preferences** (Ctrl+Alt+S / Cmd+,)
2. **Navigate to Tools → Unhook**
3. **Configure settings**:
   * Auto-refresh interval
   * Notification preferences
   * Default webhook ID
   * API endpoint

### Environment Variables

Set configuration via environment variables:

```bash theme={null}
# API configuration
NEXT_PUBLIC_API_URL=https://app.unhook.sh
NEXT_PUBLIC_WEBHOOK_BASE_URL=https://unhook.sh

# Authentication
UNHOOK_API_KEY=your_api_key
```

## Usage Guide

### Opening the Unhook Tool Window

1. **View → Tool Windows → Unhook**
2. **Or use the Unhook icon** in the tool window bar
3. **The tool window appears** at the bottom of your IDE

### Viewing Webhook Events

1. **Open the Unhook tool window**
2. **Browse events** in the event list
3. **Click on an event** to view details
4. **Use filters** to find specific events

### Inspecting Event Details

When you click on a webhook event, you'll see:

<Steps>
  <Step title="Event Information">
    * Event ID, provider, type, and timestamp
    * Success/failure status and response time
  </Step>

  <Step title="Request Details">
    * HTTP method and URL
    * Headers and request body
    * Provider-specific metadata
  </Step>

  <Step title="Response Information">
    * HTTP status code
    * Response headers and body
    * Processing duration
  </Step>
</Steps>

### Replaying Events

1. **Select an event** from the event list
2. **Click "Replay Event"** in the event details
3. **Monitor the replay** in real-time
4. **Check your application logs** for the replayed event

### Debugging Failed Events

When webhooks fail, the plugin helps you debug:

<AccordionGroup>
  <Accordion title="Check Response Status">
    Look at the HTTP status code returned by your endpoint
  </Accordion>

  <Accordion title="Review Error Messages">
    Check the response body for error details
  </Accordion>

  <Accordion title="Verify Headers">
    Ensure your endpoint is handling required headers correctly
  </Accordion>

  <Accordion title="Test Locally">
    Use the replay feature to test your endpoint with the same payload
  </Accordion>
</AccordionGroup>

## Integration Examples

### Stripe Webhooks

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-stripe-webhook"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
delivery:
  - destination: "stripe-handler"
```

Monitor Stripe payment events in real-time and replay them for testing.

### GitHub Webhooks

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-github-webhook"
destination:
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
delivery:
  - destination: "github-handler"
```

Track repository events like pushes, pull requests, and issues.

### Clerk Authentication

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-clerk-webhook"
destination:
  - name: "auth-handler"
    url: "http://localhost:3000/api/webhooks/clerk"
delivery:
  - destination: "auth-handler"
```

Monitor user authentication events and session changes.

## Advanced Features

### Custom Event Filtering

Filter events by various criteria:

* **Provider**: Filter by Stripe, GitHub, Clerk, etc.
* **Status**: Show only successful or failed events
* **Time range**: Filter by recent events
* **Event type**: Filter by specific event types

### Event Export

Export webhook events for analysis:

1. **Select events** in the event list
2. **Right-click** and choose "Export Events"
3. **Choose format** (JSON, CSV)
4. **Download** the exported file

### Performance Monitoring

Track webhook performance metrics:

* **Response times**: Monitor how fast your endpoints respond
* **Success rates**: Track webhook delivery success
* **Error patterns**: Identify common failure causes

### IDE Integration

The plugin integrates seamlessly with your IDE:

* **Project-aware**: Automatically detects project configuration
* **Run configurations**: Create run configurations for webhook testing
* **Debug integration**: Use IDE debugger with webhook replay
* **Version control**: Track webhook configuration changes

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Plugin Not Loading">
    * Restart your IDE
    * Check if the plugin is properly installed
    * Verify you're signed in to Unhook
  </Accordion>

  <Accordion title="No Events Showing">
    * Verify your webhook is active
    * Check your webhook URL is correctly configured
    * Ensure you have the correct permissions
  </Accordion>

  <Accordion title="Authentication Issues">
    * Sign out and sign back in
    * Check your internet connection
    * Verify your Unhook account is active
  </Accordion>

  <Accordion title="Replay Not Working">
    * Check your local server is running
    * Verify the endpoint URL is correct
    * Check your server logs for errors
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug mode for detailed logging:

1. **Open Settings/Preferences** (Ctrl+Alt+S / Cmd+,)
2. **Navigate to Tools → Unhook**
3. **Enable "Debug Mode"**
4. **Check the IDE log** for plugin messages

### Plugin Logs

View plugin logs for troubleshooting:

1. **Help → Diagnostic Tools → Debug Log Settings**
2. **Add "com.unhook"** to the loggers
3. **Restart your IDE**
4. **Check the log file** for detailed information

## Best Practices

1. **Keep the tool window open**: Monitor webhooks while coding
2. **Use event replay**: Test your handlers with real data
3. **Filter events**: Focus on relevant events for your development
4. **Export for analysis**: Save important events for later review
5. **Collaborate with team**: Share events for debugging sessions
6. **Use project configuration**: Keep webhook settings in version control

## Keyboard Shortcuts

| Action                  | Windows/Linux  | macOS         |
| ----------------------- | -------------- | ------------- |
| Open Unhook tool window | `Alt+U`        | `Cmd+U`       |
| Refresh events          | `Ctrl+R`       | `Cmd+R`       |
| Replay selected event   | `Ctrl+Shift+R` | `Cmd+Shift+R` |
| Export events           | `Ctrl+Shift+E` | `Cmd+Shift+E` |

## IDE-Specific Features

### IntelliJ IDEA

* **Run configurations**: Create webhook testing run configurations
* **Debug integration**: Use the debugger with webhook replay
* **Project structure**: Organize webhook configurations in project structure

### WebStorm

* **JavaScript debugging**: Debug webhook handlers with full JavaScript support
* **TypeScript support**: Full TypeScript integration for webhook development
* **Node.js integration**: Seamless Node.js debugging

### PyCharm

* **Python debugging**: Debug Python webhook handlers
* **Django/Flask integration**: Framework-specific webhook support
* **Virtual environment**: Use project virtual environments

## Next Steps

* [CLI Tool](/solutions/cli-tool) - Command line webhook testing
* [VS Code Extension](/solutions/vscode-extension) - VS Code integration
* [Team Collaboration](/solutions/team-collaboration) - Work with your team
* [Provider Integrations](/solutions/provider-integrations) - Connect with services


# MCP Server
Source: https://docs.unhook.sh/solutions/mcp-server

AI-powered webhook debugging with Model Context Protocol

# MCP Server

The Unhook MCP (Model Context Protocol) server enables AI assistants to access and analyze your webhook data, providing intelligent debugging and insights for webhook development.

## Overview

The MCP server allows AI assistants like Claude, Cursor, and other AI tools to:

* Search and analyze webhook events
* Provide intelligent debugging recommendations
* Generate performance reports
* Identify patterns in webhook failures
* Offer contextual assistance for webhook development

## What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI models to external data sources and tools. The Unhook MCP server provides a bridge between AI assistants and your webhook data, enabling intelligent analysis and debugging.

## Installation

### For Claude Desktop

1. **Download the MCP server** from the [Unhook releases page](https://github.com/unhook-sh/unhook/releases)
2. **Add to Claude Desktop**:
   * Open Claude Desktop settings
   * Go to "Connections" → "Add connection"
   * Select "MCP Server"
   * Choose the Unhook MCP server binary
3. **Configure authentication**:
   * Add your Unhook API key
   * Test the connection

### For Cursor

1. **Install the MCP extension** in Cursor
2. **Configure the Unhook server**:
   * Add your API key
   * Set the server endpoint
3. **Enable in your workspace**

### For Other AI Tools

The MCP server is compatible with any tool that supports the Model Context Protocol:

```bash theme={null}
# Example configuration
{
  "mcpServers": {
    "unhook": {
      "command": "unhook-mcp-server",
      "args": ["--api-key", "your_api_key"]
    }
  }
}
```

## Features

### Intelligent Webhook Analysis

AI assistants can now analyze your webhook data:

<CardGroup>
  <Card title="Event Search" icon="search">
    Search webhook events by provider, status, time range, and more
  </Card>

  <Card title="Failure Analysis" icon="bug">
    Identify patterns in webhook failures and suggest fixes
  </Card>

  <Card title="Performance Insights" icon="gauge-high">
    Analyze response times and success rates
  </Card>

  <Card title="Debugging Assistance" icon="lightbulb">
    Get contextual help for webhook development issues
  </Card>
</CardGroup>

### AI-Powered Debugging

Get intelligent recommendations for webhook issues:

```typescript theme={null}
// Ask your AI assistant:
"Show me all failed Stripe webhooks from the last hour"

// The AI will use the MCP server to:
// 1. Search for failed Stripe events
// 2. Analyze error patterns
// 3. Suggest specific fixes
// 4. Provide debugging steps
```

### Performance Monitoring

Track webhook performance with AI insights:

```typescript theme={null}
// Ask for performance analysis:
"Generate a performance report for my webhooks"

// The AI provides:
// - Success/failure rates by provider
// - Response time analysis
// - Error pattern identification
// - Optimization recommendations
```

## Available Tools

### search\_events

Search webhook events with filtering options.

**Parameters:**

* `webhookId` (optional): Filter by specific webhook
* `status` (optional): Filter by success/failed/pending
* `limit` (optional): Maximum number of events (1-100)

**Example:**

```typescript theme={null}
// Search for failed Stripe events
{
  "name": "search_events",
  "arguments": {
    "webhookId": "wh_stripe_prod",
    "status": "failed",
    "limit": 50
  }
}
```

### analyze\_event

Get detailed analysis of a specific webhook event.

**Parameters:**

* `eventId` (required): The ID of the event to analyze

**Example:**

```typescript theme={null}
// Analyze a specific failure
{
  "name": "analyze_event",
  "arguments": {
    "eventId": "evt_1234567890"
  }
}
```

### get\_webhook\_stats

Get comprehensive statistics for webhooks.

**Parameters:**

* `webhookId` (optional): Get stats for specific webhook
* `timeRange` (optional): Time range (1h, 24h, 7d, 30d)

**Example:**

```typescript theme={null}
// Get performance stats
{
  "name": "get_webhook_stats",
  "arguments": {
    "webhookId": "wh_stripe_prod",
    "timeRange": "24h"
  }
}
```

## Usage Examples

### Debugging Webhook Failures

```typescript theme={null}
// Ask your AI assistant:
"Debug why my Stripe webhooks are failing"

// The AI will:
// 1. Search for recent failed Stripe events
// 2. Analyze error patterns
// 3. Check response codes and error messages
// 4. Suggest specific fixes based on the data
// 5. Provide debugging steps
```

### Performance Analysis

```typescript theme={null}
// Ask for performance insights:
"Analyze webhook performance for the last week"

// The AI provides:
// - Success rate trends
// - Response time analysis
// - Provider-specific insights
// - Optimization recommendations
```

### Event Investigation

```typescript theme={null}
// Investigate specific events:
"Show me the payload for event evt_1234567890"

// The AI will:
// 1. Retrieve the specific event
// 2. Show the full payload
// 3. Highlight important fields
// 4. Explain what the event represents
```

## Configuration

### API Key Setup

1. **Get your API key** from the Unhook dashboard
2. **Configure in your AI tool**:
   ```bash theme={null}
   # Set environment variable
   export UNHOOK_API_KEY=your_api_key

   # Or configure in tool settings
   ```

### Server Configuration

Configure the MCP server for your environment:

```json theme={null}
{
  "mcpServers": {
    "unhook": {
      "command": "unhook-mcp-server",
      "args": [
        "--api-key", "your_api_key",
        "--endpoint", "https://app.unhook.sh/api/mcp",
        "--timeout", "30000"
      ]
    }
  }
}
```

### Authentication

The MCP server uses your Unhook API key for authentication:

1. **Generate API key** in Unhook dashboard
2. **Set in environment** or configuration
3. **Test connection** with your AI tool

## Integration Examples

### Claude Desktop

```bash theme={null}
# Add to Claude Desktop connections
{
  "name": "Unhook Webhooks",
  "command": "unhook-mcp-server",
  "args": ["--api-key", "your_api_key"]
}
```

### Cursor AI

```json theme={null}
// Cursor settings
{
  "mcp": {
    "servers": {
      "unhook": {
        "command": "unhook-mcp-server",
        "args": ["--api-key", "your_api_key"]
      }
    }
  }
}
```

### Custom AI Tools

```typescript theme={null}
// Example integration
import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  server: {
    command: 'unhook-mcp-server',
    args: ['--api-key', process.env.UNHOOK_API_KEY]
  }
});

// Use the client to access webhook data
const events = await client.tools.call('search_events', {
  status: 'failed',
  limit: 10
});
```

## Advanced Features

### Custom Prompts

Create custom prompts for specific webhook scenarios:

```typescript theme={null}
// Example prompt for debugging Stripe webhooks
const stripeDebugPrompt = `
Analyze the failed Stripe webhooks and provide:
1. Common error patterns
2. Specific fixes for each error type
3. Code examples for handling the errors
4. Testing recommendations
`;
```

### Automated Analysis

Set up automated webhook analysis:

```typescript theme={null}
// Daily webhook health check
const dailyReport = `
Generate a daily webhook report with:
- Total events processed
- Success/failure rates by provider
- New error types since yesterday
- Performance degradation warnings
- Top 3 issues to address
`;
```

### Pattern Recognition

Identify patterns in webhook behavior:

```typescript theme={null}
// Pattern analysis
const patternAnalysis = `
Find patterns in webhook failures:
- Time-based patterns (specific hours/days)
- Provider-specific issues
- Error type clustering
- Response time correlations
`;
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Connection Issues">
    * Verify your API key is correct
    * Check internet connectivity
    * Ensure the MCP server binary is executable
  </Accordion>

  <Accordion title="Authentication Errors">
    * Regenerate your API key
    * Check key permissions
    * Verify the key is properly set in configuration
  </Accordion>

  <Accordion title="No Data Available">
    * Ensure you have active webhooks
    * Check webhook permissions
    * Verify the time range for queries
  </Accordion>

  <Accordion title="Tool Not Found">
    * Update to the latest MCP server version
    * Check tool compatibility
    * Verify server configuration
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug mode for detailed logging:

```bash theme={null}
# Run with debug logging
unhook-mcp-server --debug --api-key your_api_key

# Check logs for connection and authentication issues
```

## Best Practices

1. **Use specific queries**: Ask for specific data rather than general requests
2. **Leverage time ranges**: Use appropriate time ranges for analysis
3. **Combine tools**: Use multiple tools together for comprehensive analysis
4. **Save important insights**: Export or document important findings
5. **Regular monitoring**: Set up regular webhook health checks

## Security Considerations

* **API Key Protection**: Keep your API key secure and rotate regularly
* **Data Access**: The MCP server only accesses your organization's webhook data
* **Rate Limiting**: Respect API rate limits to avoid throttling
* **Audit Logs**: Monitor MCP server access for security purposes

## Next Steps

* [CLI Tool](/solutions/cli-tool) - Command line webhook testing
* [VS Code Extension](/solutions/vscode-extension) - IDE integration
* [Team Collaboration](/solutions/team-collaboration) - Work with your team
* [Provider Integrations](/solutions/provider-integrations) - Connect with services
* [API Reference](/api-reference/mcp/overview) - Detailed MCP API documentation


# Provider Integrations
Source: https://docs.unhook.sh/solutions/provider-integrations

Connect with popular webhook providers like Stripe, GitHub, and Clerk

# Provider Integrations

Unhook provides built-in support for major webhook providers, making it easy to test and debug webhooks from popular services like Stripe, GitHub, Clerk, and many more.

## Overview

Unhook supports webhook providers across multiple categories:

<CardGroup>
  <Card title="Payment Processing" icon="credit-card">
    Stripe, PayPal, Square, and more
  </Card>

  <Card title="Version Control" icon="git-branch">
    GitHub, GitLab, Bitbucket
  </Card>

  <Card title="Authentication" icon="shield">
    Clerk, Auth0, Supabase Auth
  </Card>

  <Card title="Communication" icon="message-circle">
    Slack, Discord, Twilio
  </Card>

  <Card title="E-commerce" icon="shopping-cart">
    Shopify, WooCommerce, BigCommerce
  </Card>

  <Card title="Custom Providers" icon="settings">
    Any webhook-enabled service
  </Card>
</CardGroup>

## Supported Providers

### Payment Processing

#### Stripe

The most popular payment processor with comprehensive webhook support.

**Supported Events:**

* `payment_intent.succeeded`
* `payment_intent.payment_failed`
* `invoice.payment_succeeded`
* `customer.subscription.created`
* `charge.succeeded`
* And 100+ more events

**Configuration:**

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-stripe-webhook"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
source:
  - name: "stripe"
delivery:
  - source: "stripe"
    destination: "stripe-handler"
```

**Stripe Dashboard Setup:**

1. Go to Stripe Dashboard → Webhooks
2. Add endpoint: `https://unhook.sh/your-org/your-stripe-webhook`
3. Select events to listen for
4. Save webhook

#### PayPal

PayPal's webhook system for payment notifications.

**Supported Events:**

* `PAYMENT.CAPTURE.COMPLETED`
* `PAYMENT.CAPTURE.DENIED`
* `CHECKOUT.ORDER.APPROVED`
* `BILLING.SUBSCRIPTION.CREATED`

**Configuration:**

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-paypal-webhook"
destination:
  - name: "paypal-handler"
    url: "http://localhost:3000/api/webhooks/paypal"
source:
  - name: "paypal"
delivery:
  - source: "paypal"
    destination: "paypal-handler"
```

### Version Control

#### GitHub

GitHub webhooks for repository events and actions.

**Supported Events:**

* `push` - Code pushes to repository
* `pull_request` - Pull request events
* `issues` - Issue creation and updates
* `release` - Release creation
* `workflow_run` - GitHub Actions workflow runs

**Configuration:**

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-github-webhook"
destination:
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
source:
  - name: "github"
delivery:
  - source: "github"
    destination: "github-handler"
```

**GitHub Repository Setup:**

1. Go to repository Settings → Webhooks
2. Add webhook: `https://unhook.sh/your-org/your-github-webhook`
3. Select events to listen for
4. Set content type to `application/json`
5. Save webhook

#### GitLab

GitLab webhooks for repository and CI/CD events.

**Supported Events:**

* `Push Hook` - Code pushes
* `Merge Request Hook` - Merge request events
* `Pipeline Hook` - CI/CD pipeline events
* `Issue Hook` - Issue events

### Authentication

#### Clerk

Modern authentication platform with comprehensive webhook support.

**Supported Events:**

* `user.created`
* `user.updated`
* `user.deleted`
* `session.created`
* `session.ended`
* `organization.created`

**Configuration:**

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-clerk-webhook"
destination:
  - name: "clerk-handler"
    url: "http://localhost:3000/api/webhooks/clerk"
source:
  - name: "clerk"
delivery:
  - source: "clerk"
    destination: "clerk-handler"
```

**Clerk Dashboard Setup:**

1. Go to Clerk Dashboard → Webhooks
2. Add endpoint: `https://unhook.sh/your-org/your-clerk-webhook`
3. Select events to listen for
4. Save webhook

#### Auth0

Auth0's webhook system for authentication events.

**Supported Events:**

* `post-login`
* `post-registration`
* `post-change-password`
* `post-user-creation`

### Communication

#### Slack

Slack webhooks for workspace events and interactions.

**Supported Events:**

* `message` - New messages in channels
* `reaction_added` - Emoji reactions
* `channel_created` - New channels
* `team_join` - New team members

#### Discord

Discord webhooks for server events.

**Supported Events:**

* `MESSAGE_CREATE` - New messages
* `MEMBER_JOIN` - New members
* `CHANNEL_CREATE` - New channels
* `GUILD_MEMBER_UPDATE` - Member updates

### E-commerce

#### Shopify

Shopify webhooks for store events.

**Supported Events:**

* `orders/create` - New orders
* `products/create` - New products
* `customers/create` - New customers
* `inventory_levels/update` - Inventory changes

**Configuration:**

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-shopify-webhook"
destination:
  - name: "shopify-handler"
    url: "http://localhost:3000/api/webhooks/shopify"
source:
  - name: "shopify"
delivery:
  - source: "shopify"
    destination: "shopify-handler"
```

## Custom Provider Support

### Generic Webhook Support

Unhook supports any webhook-enabled service through generic webhook handling:

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-custom-webhook"
destination:
  - name: "custom-handler"
    url: "http://localhost:3000/api/webhooks/custom"
source:
  - name: "custom"
delivery:
  - source: "custom"
    destination: "custom-handler"
```

### Custom Provider Configuration

Configure custom providers with specific requirements:

```yaml theme={null}
# unhook.yaml
webhookId: "wh_custom_api"
destination:
  - name: "custom-api-handler"
    url: "http://localhost:3000/api/webhooks/custom"
    headers:
      x-api-key: "your_api_key"
      x-custom-header: "custom_value"
source:
  - name: "custom-api"
delivery:
  - source: "custom-api"
    destination: "custom-api-handler"
```

## Provider-Specific Features

### Signature Verification

Many providers include signature verification for security:

#### Stripe Signature Verification

```typescript theme={null}
// Verify Stripe webhook signature
import { headers } from 'next/headers';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(request: Request) {
  const body = await request.text();
  const signature = headers().get('stripe-signature');

  try {
    const event = stripe.webhooks.constructEvent(body, signature!, webhookSecret);
    // Process the event
    return Response.json({ received: true });
  } catch (err) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 });
  }
}
```

#### GitHub Signature Verification

```typescript theme={null}
// Verify GitHub webhook signature
import crypto from 'crypto';

export async function POST(request: Request) {
  const body = await request.text();
  const signature = headers().get('x-hub-signature-256');
  const secret = process.env.GITHUB_WEBHOOK_SECRET!;

  const expectedSignature = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')}`;

  if (signature !== expectedSignature) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = JSON.parse(body);
  // Process the event
  return Response.json({ received: true });
}
```

### Event Filtering

Filter events by type for specific providers:

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-stripe-filtered-webhook"
destination:
  - name: "stripe-payments"
    url: "http://localhost:3000/api/webhooks/stripe/payments"
  - name: "stripe-subscriptions"
    url: "http://localhost:3000/api/webhooks/stripe/subscriptions"
source:
  - name: "stripe"
    events:
      - "payment_intent.succeeded"
      - "payment_intent.payment_failed"
      - "customer.subscription.created"
      - "customer.subscription.updated"
delivery:
  - source: "stripe"
    events: ["payment_intent.*"]
    destination: "stripe-payments"
  - source: "stripe"
    events: ["customer.subscription.*"]
    destination: "stripe-subscriptions"
```

## Integration Examples

### Multi-Provider Setup

Handle multiple providers in a single configuration:

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-multi-provider-webhook"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
  - name: "clerk-handler"
    url: "http://localhost:3000/api/webhooks/clerk"
source:
  - name: "stripe"
  - name: "github"
  - name: "clerk"
delivery:
  - source: "stripe"
    destination: "stripe-handler"
  - source: "github"
    destination: "github-handler"
  - source: "clerk"
    destination: "clerk-handler"
```

### Environment-Specific Providers

Different providers for different environments:

```yaml theme={null}
# unhook.dev.yaml
webhookUrl: "https://unhook.sh/your-org/your-dev-webhook"
destination:
  - name: "stripe-test"
    url: "http://localhost:3000/api/webhooks/stripe"
source:
  - name: "stripe"
    mode: "test"  # Use Stripe test mode
delivery:
  - source: "stripe"
    destination: "stripe-test"

# unhook.prod.yaml
webhookUrl: "https://unhook.sh/your-org/your-prod-webhook"
destination:
  - name: "stripe-live"
    url: "http://localhost:3000/api/webhooks/stripe"
source:
  - name: "stripe"
    mode: "live"  # Use Stripe live mode
delivery:
  - source: "stripe"
    destination: "stripe-live"
```

## Testing Provider Integrations

### Local Testing

Test provider integrations locally:

```bash theme={null}
# Start webhook listener
unhook listen --port 3000 --webhook-url https://unhook.sh/your-org/your-stripe-test-webhook

# Test with curl
curl -X POST http://localhost:3000/api/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: ..." \
  -d '{"type":"payment_intent.succeeded","data":{...}}'
```

### Provider-Specific Testing

Use provider testing tools:

#### Stripe CLI

```bash theme={null}
# Install Stripe CLI
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger test events
stripe trigger payment_intent.succeeded
```

#### GitHub Webhook Testing

```bash theme={null}
# Use GitHub's webhook testing feature
# Go to repository Settings → Webhooks → Recent Deliveries
# Click on any delivery to see the payload
```

## Troubleshooting

### Common Provider Issues

<AccordionGroup>
  <Accordion title="Signature Verification Failures">
    * Verify webhook secret is correct
    * Check signature header format
    * Ensure payload hasn't been modified
  </Accordion>

  <Accordion title="Event Not Received">
    * Check webhook URL is correct
    * Verify events are selected in provider dashboard
    * Check webhook is active and not disabled
  </Accordion>

  <Accordion title="Provider Rate Limits">
    * Check provider's rate limiting documentation
    * Implement exponential backoff
    * Monitor webhook delivery status
  </Accordion>

  <Accordion title="Payload Format Issues">
    * Verify content-type headers
    * Check payload structure matches provider documentation
    * Test with provider's sample payloads
  </Accordion>
</AccordionGroup>

### Provider-Specific Debugging

#### Stripe Debugging

```bash theme={null}
# Check Stripe webhook logs
stripe logs tail

# Test webhook endpoint
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

#### GitHub Debugging

```bash theme={null}
# Check webhook delivery status
# Go to repository Settings → Webhooks → Recent Deliveries
# Look for failed deliveries and error messages
```

## Best Practices

### Provider Configuration

1. **Use environment-specific webhooks**: Separate test and production webhooks
2. **Implement signature verification**: Always verify webhook signatures
3. **Handle idempotency**: Webhooks may be delivered multiple times
4. **Monitor webhook health**: Track delivery success rates

### Security Considerations

1. **Keep secrets secure**: Store webhook secrets in environment variables
2. **Verify signatures**: Always verify webhook signatures for security
3. **Use HTTPS**: Ensure all webhook endpoints use HTTPS
4. **Monitor access**: Track webhook access and usage

### Performance Optimization

1. **Process webhooks asynchronously**: Don't block on webhook processing
2. **Implement retry logic**: Handle temporary failures gracefully
3. **Monitor response times**: Keep webhook processing fast
4. **Use webhook queues**: Queue webhooks for background processing

## Next Steps

* [CLI Tool](/solutions/cli-tool) - Test webhooks locally
* [VS Code Extension](/solutions/vscode-extension) - Monitor webhooks in your editor
* [Team Collaboration](/solutions/team-collaboration) - Share webhooks with your team
* [Security Features](/solutions/security) - Learn about webhook security


# Team Collaboration
Source: https://docs.unhook.sh/solutions/team-collaboration

Share webhook URLs and collaborate with your development team

# Team Collaboration

Unhook's team collaboration features enable development teams to share webhook URLs while maintaining individual development environments, streamlining webhook testing and debugging across the entire team.

## Overview

Team collaboration in Unhook provides:

* Shared webhook URLs across your entire team
* Individual developer environments with automatic routing
* Real-time team activity monitoring
* Centralized webhook configuration management
* Seamless onboarding for new team members

## How It Works

### Shared Webhook URLs

Instead of each developer having their own webhook URL, the entire team uses a single shared URL:

```
https://unhook.sh/wh_team_webhook_id
```

This URL is configured in your webhook provider (Stripe, GitHub, Clerk, etc.) and automatically routes webhooks to the active developer.

### Intelligent Routing

When a webhook is received, Unhook intelligently routes it to the appropriate developer:

<Steps>
  <Step title="Webhook Reception">
    Provider sends webhook to the shared URL
  </Step>

  <Step title="Active Session Detection">
    Unhook identifies which team member is currently active
  </Step>

  <Step title="Automatic Routing">
    Webhook is delivered to the active developer's local environment
  </Step>

  <Step title="Team Visibility">
    All team members can see the webhook event in their dashboard
  </Step>
</Steps>

## Team Setup

### Creating a Team Webhook

1. **Create a new webhook** in the Unhook dashboard
2. **Set webhook type** to "Team"
3. **Invite team members** to the webhook
4. **Share the webhook URL** with your team

### Team Member Onboarding

New team members can join easily:

```bash theme={null}
# 1. Install Unhook CLI
npm install -g @unhook/cli

# 2. Initialize with team webhook
npx @unhook/cli init --webhook-id wh_team_webhook_id

# 3. Start listening
unhook listen --port 3000
```

### Configuration Sharing

Share webhook configuration across your team:

```yaml theme={null}
# unhook.yaml (shared in repository)
webhookUrl: "https://unhook.sh/your-org/your-team-webhook"
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "local"
  - source: "github"
    destination: "local"
```

## Features

### Real-time Team Activity

Monitor team activity in real-time:

<CardGroup>
  <Card title="Active Developers" icon="user-check">
    See which team members are currently online
  </Card>

  <Card title="Webhook Events" icon="radio">
    View all webhook events across the team
  </Card>

  <Card title="Event Routing" icon="route">
    Track which developer received each webhook
  </Card>

  <Card title="Team Statistics" icon="bar-chart">
    Monitor team-wide webhook performance
  </Card>
</CardGroup>

### Individual Environments

Each developer maintains their own local environment:

```bash theme={null}
# Developer 1
unhook listen --client-id dev1 --port 3000

# Developer 2
unhook listen --client-id dev2 --port 3001

# Developer 3
unhook listen --client-id dev3 --port 3002
```

### Centralized Configuration

Manage webhook configuration centrally:

```yaml theme={null}
# Team configuration (unhooked.yaml)
webhookUrl: "https://unhook.sh/your-org/your-team-webhook"
team:
  name: "Development Team"
  members:
    - id: "dev1"
      name: "Alice"
      port: 3000
    - id: "dev2"
      name: "Bob"
      port: 3001
    - id: "dev3"
      name: "Charlie"
      port: 3002
```

## Use Cases

### Development Team Workflow

1. **Shared Development**:
   * All developers use the same webhook URL
   * Webhooks route to the active developer
   * No need to update provider settings

2. **Testing Coordination**:
   * Coordinate webhook testing across the team
   * Avoid conflicts when multiple developers test simultaneously
   * Share webhook events for debugging

3. **Onboarding**:
   * New developers get immediate access to webhooks
   * No manual URL sharing or configuration
   * Consistent development environment

### Feature Development

```bash theme={null}
# Feature branch development
git checkout feature/new-payment-flow

# Start webhook listener
unhook listen --client-id feature-payment --port 3000

# Test new payment webhooks
# Webhooks automatically route to your environment
```

### Production Testing

```bash theme={null}
# Production webhook testing
unhook listen --client-id prod-test --port 3000

# Test production webhooks safely
# Isolated from other team members
```

## Configuration Examples

### Basic Team Setup

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-team-webhook"
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
delivery:
  - destination: "local"
```

### Advanced Team Configuration

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-team-webhook"
clientId: "dev1"  # Unique identifier for this developer
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
source:
  - name: "stripe"
  - name: "github"
delivery:
  - source: "stripe"
    destination: "stripe-handler"
  - source: "github"
    destination: "github-handler"
```

### Environment-Specific Configuration

```yaml theme={null}
# unhook.dev.yaml
webhookUrl: "https://unhook.sh/your-org/your-team-dev"
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"

# unhook.staging.yaml
webhookUrl: "https://unhook.sh/your-org/your-team-staging"
destination:
  - name: "local"
    url: "http://localhost:3001/api/webhooks"
```

## Team Management

### Inviting Team Members

1. **From the dashboard**:
   * Go to your team webhook settings
   * Click "Invite Member"
   * Enter their email address
   * Send invitation

2. **Via CLI**:
   ```bash theme={null}
   unhook team invite user@example.com
   ```

### Managing Permissions

Control team member access:

* **View**: Can see webhook events
* **Replay**: Can replay webhook events
* **Configure**: Can modify webhook settings
* **Admin**: Full administrative access

### Team Activity Monitoring

Track team activity:

```bash theme={null}
# View team status
unhook team status

# See active members
unhook team members

# Check webhook routing
unhook team routing
```

## Best Practices

### Team Coordination

1. **Use meaningful client IDs**: `dev1`, `feature-payment`, `prod-test`
2. **Coordinate testing times**: Avoid conflicts when testing simultaneously
3. **Share webhook events**: Use the dashboard to share important events
4. **Document configurations**: Keep webhook configs in version control

### Development Workflow

1. **Feature branches**: Use different client IDs for feature development
2. **Environment isolation**: Separate dev, staging, and production webhooks
3. **Testing coordination**: Communicate when testing webhooks
4. **Event sharing**: Share relevant events for debugging

### Configuration Management

1. **Version control**: Keep webhook configs in your repository
2. **Environment variables**: Use env vars for sensitive information
3. **Documentation**: Document webhook setup for new team members
4. **Regular updates**: Keep configurations up to date

## Troubleshooting

### Common Team Issues

<AccordionGroup>
  <Accordion title="Webhook Not Routing">
    * Check if you're the active developer
    * Verify your client ID is unique
    * Ensure your local server is running
  </Accordion>

  <Accordion title="Multiple Developers Active">
    * Coordinate testing times with your team
    * Use different client IDs for isolation
    * Check team activity in the dashboard
  </Accordion>

  <Accordion title="Permission Issues">
    * Verify you have the correct permissions
    * Check team membership status
    * Contact your team admin
  </Accordion>

  <Accordion title="Configuration Conflicts">
    * Use environment-specific configs
    * Avoid conflicting port numbers
    * Coordinate configuration changes
  </Accordion>
</AccordionGroup>

### Debug Team Routing

```bash theme={null}
# Check team status
unhook team status

# View routing information
unhook team routing --verbose

# Check your client ID
unhook status
```

## Security Considerations

### Team Access Control

* **Role-based permissions**: Control access based on team roles
* **Audit logging**: Track who accessed what webhook data
* **Secure sharing**: Webhook data is encrypted and secure
* **Access revocation**: Remove team member access when needed

### Data Privacy

* **Organization isolation**: Teams can only access their own webhooks
* **Event privacy**: Webhook events are private to your team
* **Secure transmission**: All data is encrypted in transit
* **No data retention**: Webhook payloads are not permanently stored

## Integration Examples

### Stripe Team Webhooks

```yaml theme={null}
# Team Stripe configuration
webhookUrl: "https://unhook.sh/your-org/your-team-stripe"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
delivery:
  - destination: "stripe-handler"
```

Configure in Stripe dashboard: `https://unhook.sh/wh_team_stripe`

### GitHub Team Webhooks

```yaml theme={null}
# Team GitHub configuration
webhookUrl: "https://unhook.sh/your-org/your-team-github"
destination:
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
delivery:
  - destination: "github-handler"
```

Configure in GitHub repository: `https://unhook.sh/wh_team_github`

### Multi-Provider Team Setup

```yaml theme={null}
# Comprehensive team setup
webhookUrl: "https://unhook.sh/your-org/your-team-comprehensive"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
  - name: "clerk-handler"
    url: "http://localhost:3000/api/webhooks/clerk"
source:
  - name: "stripe"
  - name: "github"
  - name: "clerk"
delivery:
  - source: "stripe"
    destination: "stripe-handler"
  - source: "github"
    destination: "github-handler"
  - source: "clerk"
    destination: "clerk-handler"
```

## Next Steps

* [CLI Tool](/solutions/cli-tool) - Command line webhook testing
* [VS Code Extension](/solutions/vscode-extension) - IDE integration
* [Provider Integrations](/solutions/provider-integrations) - Connect with services
* [Security Features](/solutions/security) - Learn about data protection


# VS Code Extension
Source: https://docs.unhook.sh/solutions/vscode-extension

Monitor and debug webhooks directly in VS Code

# VS Code Extension

The Unhook VS Code extension provides seamless webhook monitoring and debugging directly within your development environment, eliminating the need to switch between your editor and external tools.

## Overview

The VS Code extension enables you to:

* View webhook events in real-time within VS Code
* Inspect webhook payloads and responses
* Replay webhook events for testing
* Debug webhook issues without leaving your editor
* Collaborate with team members on webhook development

## Installation

Install the extension from the VS Code marketplace:

1. **Open VS Code**
2. **Go to Extensions** (Ctrl+Shift+X / Cmd+Shift+X)
3. **Search for "Unhook"**
4. **Click Install**

Or install directly from the command line:

```bash theme={null}
code --install-extension unhook.unhook-vscode
```

## Quick Start

1. **Sign in to Unhook**:
   * Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   * Run "Unhook: Sign In"
   * Follow the authentication flow

2. **View webhook events**:
   * Open the Unhook sidebar (Unhook icon in the activity bar)
   * See real-time webhook events as they arrive

3. **Inspect and replay events**:
   * Click on any webhook event to view details
   * Use the "Replay Event" button to resend the webhook

## Features

### Real-time Webhook Monitoring

Monitor webhook events as they happen without leaving your editor:

<CardGroup>
  <Card title="Live Event Feed" icon="radio">
    See webhook events in real-time as they arrive from providers
  </Card>

  <Card title="Event Details" icon="search">
    Inspect headers, payloads, and response data for each event
  </Card>

  <Card title="Status Tracking" icon="check-circle">
    Track success/failure status and response times
  </Card>

  <Card title="Provider Filtering" icon="filter">
    Filter events by provider (Stripe, GitHub, Clerk, etc.)
  </Card>
</CardGroup>

### Webhook Event Inspection

Dive deep into webhook data with comprehensive inspection tools:

```json theme={null}
{
  "event": {
    "id": "evt_1234567890",
    "provider": "stripe",
    "type": "payment_intent.succeeded",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "status": "success"
  },
  "request": {
    "method": "POST",
    "url": "https://unhook.sh/wh_stripe_prod",
    "headers": {
      "content-type": "application/json",
      "stripe-signature": "..."
    },
    "body": {
      "id": "pi_123",
      "object": "payment_intent",
      "amount": 1000,
      "currency": "usd"
    }
  },
  "response": {
    "status": 200,
    "headers": {...},
    "body": {...},
    "duration": 245
  }
}
```

### Event Replay

Test your webhook handlers by replaying events:

1. **Select an event** from the sidebar
2. **Click "Replay Event"** button
3. **Monitor the response** in real-time
4. **Debug any issues** with your webhook handler

### Team Collaboration

Work seamlessly with your team on webhook development:

* **Shared webhook URLs**: Use the same webhook URL across your team
* **Real-time updates**: See when team members are active
* **Event sharing**: Share specific events with team members for debugging

## Configuration

### Workspace Configuration

Create an `unhook.yaml` file in your project root:

```yaml theme={null}
webhookUrl: "https://unhook.sh/your-org/your-webhook-name"
server:
  apiUrl: "https://app.unhook.sh"
destination:
  - name: "local"
    url: "http://localhost:3000/api/webhooks"
delivery:
  - destination: "local"
```

### VS Code Settings

Configure the extension through VS Code settings:

```json theme={null}
{
  "unhook.configFilePath": "./unhook.yaml",
  "unhook.autoRefresh": true,
  "unhook.refreshInterval": 5000,
  "unhook.showNotifications": true
}
```

### Environment Variables

Set configuration via environment variables:

```bash theme={null}
# API configuration
NEXT_PUBLIC_API_URL=https://app.unhook.sh
NEXT_PUBLIC_WEBHOOK_BASE_URL=https://unhook.sh

# Authentication
UNHOOK_API_KEY=your_api_key
```

## Usage Guide

### Viewing Webhook Events

1. **Open the Unhook sidebar** (click the Unhook icon in the activity bar)
2. **Browse events** in the event list
3. **Click on an event** to view details
4. **Use filters** to find specific events

### Inspecting Event Details

When you click on a webhook event, you'll see:

<Steps>
  <Step title="Event Information">
    * Event ID, provider, type, and timestamp
    * Success/failure status and response time
  </Step>

  <Step title="Request Details">
    * HTTP method and URL
    * Headers and request body
    * Provider-specific metadata
  </Step>

  <Step title="Response Information">
    * HTTP status code
    * Response headers and body
    * Processing duration
  </Step>
</Steps>

### Replaying Events

1. **Select an event** from the sidebar
2. **Click "Replay Event"** in the event details
3. **Monitor the replay** in real-time
4. **Check your application logs** for the replayed event

### Debugging Failed Events

When webhooks fail, the extension helps you debug:

<AccordionGroup>
  <Accordion title="Check Response Status">
    Look at the HTTP status code returned by your endpoint
  </Accordion>

  <Accordion title="Review Error Messages">
    Check the response body for error details
  </Accordion>

  <Accordion title="Verify Headers">
    Ensure your endpoint is handling required headers correctly
  </Accordion>

  <Accordion title="Test Locally">
    Use the replay feature to test your endpoint with the same payload
  </Accordion>
</AccordionGroup>

## Integration Examples

### Stripe Webhooks

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-stripe-webhook"
destination:
  - name: "stripe-handler"
    url: "http://localhost:3000/api/webhooks/stripe"
delivery:
  - destination: "stripe-handler"
```

Monitor Stripe payment events in real-time and replay them for testing.

### GitHub Webhooks

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-github-webhook"
destination:
  - name: "github-handler"
    url: "http://localhost:3000/api/webhooks/github"
delivery:
  - destination: "github-handler"
```

Track repository events like pushes, pull requests, and issues.

### Clerk Authentication

```yaml theme={null}
# unhook.yaml
webhookUrl: "https://unhook.sh/your-org/your-clerk-webhook"
destination:
  - name: "auth-handler"
    url: "http://localhost:3000/api/webhooks/clerk"
delivery:
  - destination: "auth-handler"
```

Monitor user authentication events and session changes.

## Advanced Features

### Custom Event Filtering

Filter events by various criteria:

* **Provider**: Filter by Stripe, GitHub, Clerk, etc.
* **Status**: Show only successful or failed events
* **Time range**: Filter by recent events
* **Event type**: Filter by specific event types

### Event Export

Export webhook events for analysis:

1. **Select events** in the sidebar
2. **Right-click** and choose "Export Events"
3. **Choose format** (JSON, CSV)
4. **Download** the exported file

### Performance Monitoring

Track webhook performance metrics:

* **Response times**: Monitor how fast your endpoints respond
* **Success rates**: Track webhook delivery success
* **Error patterns**: Identify common failure causes

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Extension Not Loading">
    * Restart VS Code
    * Check if the extension is properly installed
    * Verify you're signed in to Unhook
  </Accordion>

  <Accordion title="No Events Showing">
    * Verify your webhook is active
    * Check your webhook URL is correctly configured
    * Ensure you have the correct permissions
  </Accordion>

  <Accordion title="Authentication Issues">
    * Sign out and sign back in
    * Check your internet connection
    * Verify your Unhook account is active
  </Accordion>

  <Accordion title="Replay Not Working">
    * Check your local server is running
    * Verify the endpoint URL is correct
    * Check your server logs for errors
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug mode for detailed logging:

1. **Open Command Palette** (Ctrl+Shift+P / Cmd+Shift+P)
2. **Run "Developer: Toggle Developer Tools"**
3. **Check the Console tab** for extension logs

## Best Practices

1. **Keep the sidebar open**: Monitor webhooks while coding
2. **Use event replay**: Test your handlers with real data
3. **Filter events**: Focus on relevant events for your development
4. **Export for analysis**: Save important events for later review
5. **Collaborate with team**: Share events for debugging sessions

## Keyboard Shortcuts

| Action                | Windows/Linux  | macOS         |
| --------------------- | -------------- | ------------- |
| Open Unhook sidebar   | `Ctrl+Shift+U` | `Cmd+Shift+U` |
| Refresh events        | `Ctrl+R`       | `Cmd+R`       |
| Replay selected event | `Ctrl+Shift+R` | `Cmd+Shift+R` |
| Export events         | `Ctrl+Shift+E` | `Cmd+Shift+E` |

## Next Steps

* [CLI Tool](/solutions/cli-tool) - Command line webhook testing
* [Team Collaboration](/solutions/team-collaboration) - Work with your team
* [Provider Integrations](/solutions/provider-integrations) - Connect with services
* [MCP Integration](/solutions/mcp-server) - AI-powered webhook debugging


# VSCode Extension
Source: https://docs.unhook.sh/vscode-extension

The complete guide to using Unhook's VSCode extension for webhook development

# Unhook VSCode Extension

<div>
  <img alt="Unhook VSCode Extension" />
</div>

The Unhook VSCode extension brings powerful webhook development capabilities directly into your code editor. Test, debug, and collaborate on webhooks without leaving your development environment.

## Features Overview

### 🎯 **Webhook Event Explorer**

* View all webhook events in a dedicated sidebar panel
* Real-time updates as events are received
* Hierarchical view of events and their associated requests
* Quick filtering and search capabilities

### 🔄 **Request Replay & Debugging**

* Instantly replay webhook events and individual requests
* Copy event data to clipboard for analysis
* Detailed request/response inspection in a native webview
* Support for debugging failed webhook deliveries

### 👥 **Team Collaboration**

* See active team members and their webhook sessions
* Share webhook URLs while maintaining individual environments
* Real-time collaboration features

### 🔐 **Secure Authentication**

* OAuth-based authentication with Unhook
* Secure session management and token handling
* Automatic session validation and refresh

### ⚙️ **Smart Configuration**

* Automatic detection of Unhook config files in workspace
* Configurable settings for output behavior and event history
* Integration with VS Code's settings system

### 📊 **Real-Time Monitoring**

* Live webhook event monitoring in the sidebar
* Integrated output panel with configurable logging
* Status bar integration showing connection status

## Installation

### From VS Code Marketplace

1. Open VS Code
2. Go to Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`)
3. Search for "Unhook - Webhook Development"
4. Click **Install**

### From VSIX File

If you have a `.vsix` file:

1. Open VS Code
2. Go to Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`)
3. Click the `...` menu and select "Install from VSIX..."
4. Select the downloaded `.vsix` file

## Getting Started

### 1. Authentication

After installation, you'll need to authenticate with Unhook:

1. **Open the Unhook sidebar** - Click the Unhook icon in the Activity Bar
2. **Sign in** - Click "Sign in to Unhook" in the status bar or use `Ctrl+Shift+P` → "Unhook: Sign in to Unhook"
3. **Complete OAuth flow** - Your browser will open to complete authentication
4. **Return to VS Code** - The extension will automatically detect the successful authentication

<Note>
  If you don't have an Unhook account, you can create one for free at [unhook.sh](https://unhook.sh)
</Note>

### 2. Configure Your Workspace

The extension will automatically look for Unhook configuration files in your workspace:

* `unhook.yaml` or `unhook.yml` in the workspace root
* Custom path via the `unhook.configFilePath` setting

Example `unhook.yml`:

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

### 3. Start Receiving Webhooks

Once authenticated and configured:

1. **Create a webhook URL** at [unhook.sh/app](https://unhook.sh/app)
2. **Configure your webhook provider** (Stripe, GitHub, etc.) to use the Unhook URL
3. **View events in VS Code** - Events will appear in the Unhook sidebar as they're received

## Core Features

### Event Explorer Sidebar

The main interface for webhook management:

* **Events Tree View**: Hierarchical display of events and requests
* **Real-time Updates**: Events appear automatically as they're received
* **Context Actions**: Right-click for replay, copy, and view options
* **Quick Actions**: Toolbar buttons for common operations

#### Event Actions

Each event supports these actions:

* **View Event** (`👁️`) - Open detailed view in webview panel
* **Replay Event** (`▶️`) - Resend the event to all configured destinations
* **Copy Event** (`📋`) - Copy event JSON to clipboard

#### Request Actions

Individual requests within events support:

* **View Request** (`👁️`) - Open detailed request/response view
* **Replay Request** (`▶️`) - Resend just this specific request

### Request Details Webview

Beautiful, interactive panel for inspecting webhook data:

* **Request Information**: Method, URL, headers, and body
* **Response Data**: Status code, headers, and response body
* **Timing Information**: Request duration and timestamps
* **Syntax Highlighting**: JSON and other formats are beautifully formatted
* **Copy to Clipboard**: Easy copying of any data section

### Quick Pick Interface

Access common actions quickly with `Ctrl+Shift+P` → "Unhook: Quick Pick Event":

* Browse recent events
* Quick replay functionality
* Fast navigation to event details

### Status Bar Integration

The status bar shows your current Unhook connection status:

* **🔄 Validating Session** - When checking authentication
* **✅ Unhook** - Connected and ready (click for quick actions)
* **🔑 Sign in to Unhook** - Not authenticated (click to sign in)

### Output Panel Integration

Integrated logging and output management:

* **Automatic Output Panel** - Shows webhook events as they arrive
* **Configurable Behavior** - Control when the output panel appears
* **Log Management** - Automatic cleanup of old log entries
* **Manual Controls** - Clear, focus, and toggle output panel

## Commands Reference

### Authentication Commands

| Command          | Description        | Shortcut |
| ---------------- | ------------------ | -------- |
| `unhook.signIn`  | Sign in to Unhook  | -        |
| `unhook.signOut` | Sign out of Unhook | -        |

### Event Management Commands

| Command                 | Description               | Shortcut |
| ----------------------- | ------------------------- | -------- |
| `unhook.showEvents`     | Show Events sidebar       | -        |
| `unhook.addEvent`       | Add new event             | -        |
| `unhook.events.refresh` | Refresh events list       | -        |
| `unhook.events.filter`  | Filter events             | -        |
| `unhook.quickPick`      | Show Quick Pick interface | -        |

### Event Actions

| Command                | Description             | Context      |
| ---------------------- | ----------------------- | ------------ |
| `unhook.viewEvent`     | View event details      | Event item   |
| `unhook.replayEvent`   | Replay event            | Event item   |
| `unhook.copyEvent`     | Copy event to clipboard | Event item   |
| `unhook.viewRequest`   | View request details    | Request item |
| `unhook.replayRequest` | Replay request          | Request item |

### Output & Settings Commands

| Command                        | Description              | Shortcut |
| ------------------------------ | ------------------------ | -------- |
| `unhook.focusOutput`           | Focus output panel       | -        |
| `unhook.clearOutput`           | Clear output panel       | -        |
| `unhook.toggleOutput`          | Toggle output panel      | -        |
| `unhook.toggleAutoShowOutput`  | Toggle auto-show output  | -        |
| `unhook.toggleAutoClearEvents` | Toggle auto-clear events | -        |
| `unhook.toggleDelivery`        | Toggle event delivery    | -        |

## Configuration

### Extension Settings

Configure the extension through VS Code settings (`Ctrl+,` / `Cmd+,`):

#### Output Settings

```json theme={null}
{
  "unhook.output.autoShow": true,
  "unhook.output.maxLines": 1000
}
```

* **`unhook.output.autoShow`** (boolean, default: `true`)
  Automatically show the output panel when new events are received

* **`unhook.output.maxLines`** (number, default: `1000`)
  Maximum number of lines to keep in the output panel

#### Event Management Settings

```json theme={null}
{
  "unhook.events.maxHistory": 100,
  "unhook.events.autoClear": false
}
```

* **`unhook.events.maxHistory`** (number, default: `100`)
  Maximum number of events to keep in history

* **`unhook.events.autoClear`** (boolean, default: `false`)
  Automatically clear old events when the maximum history is reached

#### Configuration File Settings

```json theme={null}
{
  "unhook.configFilePath": "./custom/path/unhook.yaml"
}
```

* **`unhook.configFilePath`** (string, default: `""`)
  Path to the Unhook config file. If not set, the extension will look in the workspace root.

### Workspace Configuration

The extension integrates with your existing Unhook configuration:

```yaml theme={null}
# unhook.yml
webhookUrl: https://unhook.sh/your-org/your-webhook-name

destination:
  - name: local-dev
    url: http://localhost:3000/api/webhooks
    ping: true
  - name: staging
    url: https://staging.example.com/api/webhooks
    ping: false

source:
  - name: stripe
  - name: github

delivery:
  - source: stripe
    destination: local-dev
  - source: github
    destination: staging
```

## Advanced Usage

### Team Collaboration

When working with a team:

1. **Shared Configuration** - Use a shared `unhook.yaml` in your repository
2. **Individual API Keys** - Each team member uses their own API key
3. **Environment-Specific Destinations** - Configure different endpoints per developer

### Provider Integration

The extension works with all supported webhook providers:

* **Stripe** - Payment and subscription webhooks
* **GitHub** - Repository and organization events
* **Clerk** - Authentication and user management events
* **Discord** - Bot and server events
* **Custom Providers** - Any webhook-enabled service

### Debugging Workflows

Common debugging patterns:

1. **Event Inspection** - Use the webview to examine request/response data
2. **Selective Replay** - Replay specific events or requests for testing
3. **Local Testing** - Route webhooks to different local endpoints
4. **Response Analysis** - Check response codes and timing information

### Keyboard Shortcuts

While there are no default keyboard shortcuts, you can set custom ones:

1. Open Keyboard Shortcuts (`Ctrl+K Ctrl+S` / `Cmd+K Cmd+S`)
2. Search for "unhook"
3. Assign shortcuts to frequently used commands

Recommended shortcuts:

```json theme={null}
{
  "key": "ctrl+shift+u",
  "command": "unhook.quickPick"
},
{
  "key": "ctrl+shift+r",
  "command": "unhook.events.refresh"
}
```

## Troubleshooting

### Common Issues

#### Authentication Problems

**Issue**: "Failed to authenticate with Unhook"

* **Solution**: Sign out and sign in again using the command palette
* **Check**: Ensure you have a valid Unhook account at [unhook.sh](https://unhook.sh)

#### No Events Appearing

**Issue**: Events not showing in the sidebar

* **Check**: Verify your `unhook.yaml` configuration is correct
* **Check**: Ensure the webhook URL is properly configured with your provider
* **Solution**: Use the refresh button in the Events panel

#### Configuration Not Found

**Issue**: "No config loaded" error

* **Check**: Ensure `unhook.yaml` exists in your workspace root
* **Alternative**: Set custom path via `unhook.configFilePath` setting
* **Verify**: Check YAML syntax is valid

#### Replay Failures

**Issue**: Event replay not working

* **Check**: Ensure delivery is not paused (use "Toggle Event Delivery")
* **Check**: Verify destination URLs are accessible
* **Debug**: Check the output panel for error messages

### Debug Mode

Enable debug logging by setting the log level:

1. Open Output panel (`Ctrl+Shift+U` / `Cmd+Shift+U`)
2. Select "Unhook" from the dropdown
3. Look for detailed logging information

### Getting Help

* **Documentation**: [unhook.sh/docs](https://unhook.sh/docs)
* **GitHub Issues**: [github.com/unhook-sh/unhook/issues](https://github.com/unhook-sh/unhook/issues)
* **Discord Community**: [discord.gg/qRZzTCK6MZ](https://discord.gg/qRZzTCK6MZ)
* **Email Support**: [chris.watts.t@gmail.com](mailto:chris.watts.t@gmail.com)

## Development & Contributing

### Building from Source

```bash theme={null}
# Clone the repository
git clone https://github.com/unhook-sh/unhook.git
cd unhook/apps/vscode-extension

# Install dependencies
bun install

# Build the extension
bun run build

# Package as VSIX
bun run package
```

### Development Mode

```bash theme={null}
# Start development mode
bun run dev

# This runs both:
# - Extension compilation in watch mode
# - Webview development server
```

### Contributing

We welcome contributions! See our [Contributing Guide](https://github.com/unhook-sh/unhook/blob/main/CONTRIBUTING.md) for details.

## Changelog

See the [full changelog](https://github.com/unhook-sh/unhook/blob/main/apps/vscode-extension/CHANGELOG.md) for all updates and improvements.

## License

The Unhook VSCode Extension is open source software licensed under the MIT License.


# VSCode Extension Release Automation
Source: https://docs.unhook.sh/vscode-extension-automation

Automated release system for the VSCode extension

# VSCode Extension Release Automation

This document outlines the automated release system for the VSCode extension (`apps/vscode-extension`) that enables seamless publishing to both the Visual Studio Marketplace and Open VSX Registry.

## Implementation Overview

The automation consists of two main components:

### 1. GitHub Workflow

The workflow is defined in `.github/workflows/vscode-extension-release.yml`:

**Triggers:**

* Automatically after the "NPM Release" workflow completes
* Manual dispatch for testing/emergency releases

**Conditions:**

* Only runs when the commit message contains "chore: version packages" (indicating a version bump)
* Only runs when the VSCode extension's `package.json` version was actually changed

**Process:**

1. **Version Check**: Validates that this is a version bump commit and that the VSCode extension version specifically changed
2. **Release**: Builds, packages, publishes to both marketplaces, and creates GitHub release

### 2. Composite Action

The composite action is located at `tooling/github/vscode-extension/github-release/action.yml`:

**Steps:**

1. **Setup Environment**: Uses the shared setup action
2. **Build Extension**: Runs `bun run build` to compile the extension
3. **Package Extension**: Creates VSIX file using `bunx vsce package`
4. **Publish to Visual Studio Marketplace**: Publishes using `bunx vsce publish`
5. **Publish to Open VSX Registry**: Publishes using `bunx ovsx publish`
6. **Extract Changelog**: Reads version-specific changes from `CHANGELOG.md`
7. **Create GitHub Release**: Creates release with tag `vscode-v{version}` and attaches VSIX file

## Setup Requirements

### Required GitHub Secrets

Add the following secrets to your GitHub repository:

* `VSCE_PAT`: Personal Access Token for Visual Studio Marketplace
  * Generate at: [https://dev.azure.com/](https://dev.azure.com/)
  * Requires "Marketplace (publish)" scope
  * Should be associated with the publisher account ("unhook")

* `OVSX_PAT`: Personal Access Token for Open VSX Registry
  * Generate at: [https://open-vsx.org/user-settings/tokens](https://open-vsx.org/user-settings/tokens)
  * Requires publishing permissions
  * Should be associated with your Open VSX account

### Open VSX Registry Setup

Before publishing to Open VSX, you need to:

1. **Create an Eclipse account** at eclipse.org (use same GitHub account as open-vsx.org)
2. **Sign the Publisher Agreement** at open-vsx.org
3. **Create an access token** in your Open VSX settings
4. **Namespace creation** is handled automatically by the workflow

<Note>
  The automation will automatically create the namespace (publisher) if it doesn't exist during the first publish.
</Note>

### VSCode Extension Configuration

The automation expects:

* Extension built with Bun (already configured)
* Extension publisher set to "unhook" in `package.json` (already set)
* Changelog maintained in `apps/vscode-extension/CHANGELOG.md` with version sections like:

```markdown theme={null}
## 0.0.3
- Feature description
- Bug fix description

## 0.0.2
- Previous version changes
```

## Workflow Integration

### Automatic Process

1. **NPM Release**: Maintainer triggers NPM Release workflow (manually or via GitHub Actions)
2. **Version Bump**: Release script bumps versions and generates AI-powered changelog
3. **VSCode Release**: If VSCode extension version changed, the VSCode Extension Release workflow automatically triggers
4. **Dual Marketplace Publication**: Extension is built, packaged, and published to both Visual Studio Marketplace and Open VSX Registry
5. **GitHub Release**: Release created with VSIX file attachment

### Manual Fallback

If automation fails, manual release steps:

```bash theme={null}
# Navigate to extension directory
cd apps/vscode-extension

# Build extension
bun run build

# Package extension
bun run vsce

# Publish to Visual Studio Marketplace
bunx vsce publish

# Publish to Open VSX Registry (requires OVSX_PAT environment variable)
bun run ovsx
```

## Marketplace Coverage

Publishing to both marketplaces ensures broad compatibility:

* **Visual Studio Marketplace**: Used by Microsoft VS Code
* **Open VSX Registry**: Used by VS Code alternatives like:
  * VSCodium
  * Gitpod
  * Eclipse Theia
  * Code-OSS distributions

## Monitoring

The workflow provides clear logging for each step:

* Build status and output
* Package creation
* Visual Studio Marketplace publishing result
* Open VSX Registry publishing result
* GitHub release creation

Failed steps will be clearly indicated in the GitHub Actions logs.

## Security Considerations

* Both `VSCE_PAT` and `OVSX_PAT` are securely stored as GitHub secrets
* Tokens have minimal required permissions (marketplace publish only)
* Extension files are built from source during workflow execution
* All steps logged for audit trail

## File Structure

```
.github/workflows/
└── vscode-extension-release.yml

tooling/github/vscode-extension/
└── github-release/
    └── action.yml
```

<Note>
  The workflow only triggers when the VSCode extension version specifically changes. GitHub releases use the tag format `vscode-v{version}` to distinguish from CLI releases.
</Note>

## Best Practices

* VSIX files are automatically attached to GitHub releases for manual distribution
* The automation follows the same patterns as the existing CLI release workflow for consistency
* Version management is handled by the NPM Release workflow with AI-powered changelog generation
* Dual marketplace publishing ensures maximum compatibility across VS Code distributions