docs/zh/api-reference/endpoint/webhook.mdx

---
title: WebHooks API
description: 配置和管理 WebHook 事件通知的完整指南
---

# WebHooks API

WebHooks 允许 MCPHub 在特定事件发生时向您的应用程序发送实时通知。

## 概述

MCPHub WebHooks 系统支持以下功能：

- 实时事件通知
- 自定义过滤器
- 重试机制
- 签名验证
- 批量事件处理

## 支持的事件类型

| 事件类型                | 描述           |
| ----------------------- | -------------- |
| `server.created`        | MCP 服务器创建 |
| `server.updated`        | MCP 服务器更新 |
| `server.deleted`        | MCP 服务器删除 |
| `server.status_changed` | 服务器状态变更 |
| `group.created`         | 服务器组创建   |
| `group.updated`         | 服务器组更新   |
| `group.deleted`         | 服务器组删除   |
| `user.login`            | 用户登录       |
| `user.logout`           | 用户登出       |
| `config.changed`        | 配置变更       |
| `system.error`          | 系统错误       |

## 创建 WebHook

### 端点

```http
POST /api/webhooks
```

### 请求体

```json
{
  "url": "https://your-app.com/webhook",
  "events": ["server.created", "server.status_changed"],
  "secret": "your-webhook-secret",
  "active": true,
  "config": {
    "contentType": "application/json",
    "insecureSsl": false,
    "retryCount": 3,
    "timeout": 30
  },
  "filters": {
    "serverGroups": ["production", "staging"],
    "serverTypes": ["ai-assistant", "data-processor"]
  }
}
```

### 响应

```json
{
  "success": true,
  "data": {
    "id": "webhook-123",
    "url": "https://your-app.com/webhook",
    "events": ["server.created", "server.status_changed"],
    "active": true,
    "secret": "your-webhook-secret",
    "config": {
      "contentType": "application/json",
      "insecureSsl": false,
      "retryCount": 3,
      "timeout": 30
    },
    "filters": {
      "serverGroups": ["production", "staging"],
      "serverTypes": ["ai-assistant", "data-processor"]
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

## 获取 WebHook 列表

### 端点

```http
GET /api/webhooks
```

### 查询参数

| 参数名 | 类型    | 描述                 |
| ------ | ------- | -------------------- |
| page   | integer | 页码（默认：1）      |
| limit  | integer | 每页数量（默认：20） |
| active | boolean | 过滤活跃状态         |
| event  | string  | 过滤事件类型         |

### 请求示例

```bash
curl -X GET \
  'https://api.mcphub.io/api/webhooks?active=true&limit=10' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### 响应

```json
{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "webhook-123",
        "url": "https://your-app.com/webhook",
        "events": ["server.created", "server.status_changed"],
        "active": true,
        "lastDelivery": "2024-01-15T09:30:00Z",
        "deliveryCount": 145,
        "failureCount": 2,
        "createdAt": "2024-01-10T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  }
}
```

## 获取单个 WebHook

### 端点

```http
GET /api/webhooks/{id}
```

### 响应

```json
{
  "success": true,
  "data": {
    "id": "webhook-123",
    "url": "https://your-app.com/webhook",
    "events": ["server.created", "server.status_changed"],
    "active": true,
    "secret": "your-webhook-secret",
    "config": {
      "contentType": "application/json",
      "insecureSsl": false,
      "retryCount": 3,
      "timeout": 30
    },
    "filters": {
      "serverGroups": ["production", "staging"],
      "serverTypes": ["ai-assistant", "data-processor"]
    },
    "stats": {
      "totalDeliveries": 145,
      "successfulDeliveries": 143,
      "failedDeliveries": 2,
      "lastDelivery": "2024-01-15T09:30:00Z",
      "lastSuccess": "2024-01-15T09:30:00Z",
      "lastFailure": "2024-01-14T15:20:00Z"
    },
    "createdAt": "2024-01-10T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

## 更新 WebHook

### 端点

```http
PUT /api/webhooks/{id}
```

### 请求体

```json
{
  "url": "https://your-app.com/new-webhook",
  "events": ["server.created", "server.updated", "server.deleted"],
  "active": true,
  "config": {
    "retryCount": 5,
    "timeout": 45
  }
}
```

## 删除 WebHook

### 端点

```http
DELETE /api/webhooks/{id}
```

### 响应

```json
{
  "success": true,
  "message": "WebHook 已成功删除"
}
```

## WebHook 事件格式

### 基本结构

所有 WebHook 事件都遵循以下基本结构：

```json
{
  "id": "event-123",
  "type": "server.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    // 事件特定数据
  },
  "metadata": {
    "source": "mcphub",
    "environment": "production",
    "triggeredBy": "user-456"
  }
}
```

### 服务器事件示例

#### server.created

```json
{
  "id": "event-123",
  "type": "server.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    "server": {
      "id": "mcp-server-123",
      "name": "AI Assistant Server",
      "type": "ai-assistant",
      "endpoint": "https://ai-assistant.example.com",
      "group": "production",
      "status": "active",
      "capabilities": ["chat", "completion"],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  },
  "metadata": {
    "source": "mcphub",
    "environment": "production",
    "triggeredBy": "user-456"
  }
}
```

#### server.status_changed

```json
{
  "id": "event-124",
  "type": "server.status_changed",
  "timestamp": "2024-01-15T11:30:00Z",
  "version": "1.0",
  "data": {
    "server": {
      "id": "mcp-server-123",
      "name": "AI Assistant Server",
      "previousStatus": "active",
      "currentStatus": "inactive",
      "reason": "Health check failed",
      "lastHealthCheck": "2024-01-15T11:25:00Z"
    }
  },
  "metadata": {
    "source": "mcphub",
    "environment": "production",
    "triggeredBy": "system"
  }
}
```

## 签名验证

MCPHub 使用 HMAC-SHA256 签名来验证 WebHook 的真实性。

### 签名生成

签名在 `X-MCPHub-Signature-256` 头中发送：

```
X-MCPHub-Signature-256: sha256=5757107ea39eca8e35d1e8...
```

### 验证示例

#### Node.js

```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const actualSignature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(actualSignature, 'hex'),
  );
}

// Express.js 中间件示例
app.use('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-mcphub-signature-256'];
  const payload = req.body;

  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }

  // 处理 WebHook 事件
  const event = JSON.parse(payload);
  console.log('收到事件:', event.type);

  res.status(200).send('OK');
});
```

#### Python

```python
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    actual_signature = signature.replace('sha256=', '')

    return hmac.compare_digest(expected_signature, actual_signature)

# Flask 示例
from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-MCPHub-Signature-256')
    payload = request.get_data()

    if not verify_signature(payload, signature, 'your-webhook-secret'):
        return jsonify({'error': 'Unauthorized'}), 401

    event = json.loads(payload)
    print(f'收到事件: {event["type"]}')

    return jsonify({'status': 'success'}), 200
```

## 重试机制

MCPHub 对失败的 WebHook 交付实施指数退避重试：

- **重试次数**: 可配置（默认 3 次）
- **重试间隔**: 2^n 秒（n 为重试次数）
- **最大间隔**: 300 秒（5 分钟）
- **超时设置**: 可配置（默认 30 秒）

### 重试时间表

| 尝试次数 | 延迟时间 |
| -------- | -------- |
| 1        | 立即     |
| 2        | 2 秒     |
| 3        | 4 秒     |
| 4        | 8 秒     |
| 5        | 16 秒    |

## 获取交付历史

### 端点

```http
GET /api/webhooks/{id}/deliveries
```

### 查询参数

| 参数名     | 类型    | 描述                                 |
| ---------- | ------- | ------------------------------------ |
| page       | integer | 页码                                 |
| limit      | integer | 每页数量                             |
| status     | string  | 过滤状态（success, failed, pending） |
| event_type | string  | 过滤事件类型                         |

### 响应

```json
{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "delivery-123",
        "eventId": "event-123",
        "eventType": "server.created",
        "url": "https://your-app.com/webhook",
        "status": "success",
        "responseCode": 200,
        "responseTime": 145,
        "attempts": 1,
        "deliveredAt": "2024-01-15T10:30:15Z",
        "nextRetry": null
      },
      {
        "id": "delivery-124",
        "eventId": "event-124",
        "eventType": "server.status_changed",
        "url": "https://your-app.com/webhook",
        "status": "failed",
        "responseCode": 500,
        "responseTime": 30000,
        "attempts": 3,
        "error": "Connection timeout",
        "deliveredAt": null,
        "nextRetry": "2024-01-15T11:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 145,
      "pages": 8
    }
  }
}
```

## 测试 WebHook

### 端点

```http
POST /api/webhooks/{id}/test
```

### 请求体

```json
{
  "eventType": "server.created",
  "customData": {
    "test": true,
    "message": "这是一个测试事件"
  }
}
```

### 响应

```json
{
  "success": true,
  "data": {
    "deliveryId": "delivery-test-123",
    "status": "delivered",
    "responseCode": 200,
    "responseTime": 124,
    "sentAt": "2024-01-15T10:30:00Z"
  }
}
```

## 最佳实践

### 1. 幂等性处理

确保您的 WebHook 端点能够处理重复事件：

```javascript
const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const event = req.body;

  // 检查事件是否已处理
  if (processedEvents.has(event.id)) {
    return res.status(200).send('Already processed');
  }

  // 处理事件
  processEvent(event);

  // 记录已处理的事件
  processedEvents.add(event.id);

  res.status(200).send('OK');
});
```

### 2. 异步处理

对于复杂的处理逻辑，使用异步处理避免阻塞：

```javascript
app.post('/webhook', async (req, res) => {
  const event = req.body;

  // 立即响应
  res.status(200).send('OK');

  // 异步处理事件
  setImmediate(() => {
    processEventAsync(event);
  });
});
```

### 3. 错误处理

实施适当的错误处理和日志记录：

```javascript
app.post('/webhook', (req, res) => {
  try {
    const event = req.body;
    processEvent(event);
    res.status(200).send('OK');
  } catch (error) {
    console.error('WebHook 处理错误:', error);
    res.status(500).send('Internal Server Error');
  }
});
```

### 4. 监控和告警

监控 WebHook 的交付状态：

```bash
# 检查失败的交付
curl -X GET \
  'https://api.mcphub.io/api/webhooks/webhook-123/deliveries?status=failed' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

## 故障排除

### 常见问题

1. **签名验证失败**

   - 检查密钥是否正确
   - 确保使用原始请求体进行验证
   - 验证 HMAC 计算实现

2. **超时错误**

   - 增加 WebHook 超时设置
   - 优化端点响应时间
   - 使用异步处理

3. **重复事件**
   - 实施幂等性检查
   - 使用事件 ID 去重
   - 记录处理状态

### 调试工具

使用 MCPHub 提供的调试工具：

```bash
# 查看最近的交付日志
curl -X GET \
  'https://api.mcphub.io/api/webhooks/webhook-123/deliveries?limit=5' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

# 重新发送失败的事件
curl -X POST \
  'https://api.mcphub.io/api/webhooks/delivery-124/redeliver' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```