# 📬 Webhook 回调消息查看指南

## 概述

Tavily MCP 的回调功能通过 **HTTP POST** 请求将使用统计和告警信息发送到你指定的 Webhook URL。你需要一个服务来接收这些消息。

## 🎯 三种查看方式

### 方式 1: 在线 Webhook 测试服务（最简单）

使用 webhook.site 快速测试，无需任何设置：

#### 步骤：

1. **访问** https://webhook.site/
2. **复制**生成的唯一 URL（类似：`https://webhook.site/abc-123-def-456`）
3. **配置** Tavily MCP：

```json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key",
        "USAGE_TRACKING_ENABLED": "true",
        "USAGE_CALLBACK_URL": "https://webhook.site/abc-123-def-456",
        "USAGE_REPORT_INTERVAL": "60"
      }
    }
  }
}
```

4. **查看**：在 webhook.site 页面实时查看接收到的回调消息

**优点：**
- ✅ 无需安装任何东西
- ✅ 实时显示
- ✅ 可以查看请求详情和历史记录
- ✅ 支持自动刷新

**缺点：**
- ❌ URL 是公开的（但唯一）
- ❌ 数据保存有时间限制

---

### 方式 2: 本地 Webhook 接收服务器（推荐）

我已经为你创建了一个本地接收服务器：`webhook-receiver.js`

#### 启动服务器：

```bash
node webhook-receiver.js
```

你会看到：

```
======================================================================
🚀 Tavily MCP Webhook Receiver Started!
======================================================================

📡 Listening on http://localhost:3000
📊 View dashboard: http://localhost:3000/
🔗 Webhook endpoint: http://localhost:3000/tavily-usage
💾 Logs saved to: webhook-logs.json

📋 Configuration for Tavily MCP:
   Add this to your MCP config:
   "USAGE_CALLBACK_URL": "http://localhost:3000/tavily-usage"

⌨️  Press Ctrl+C to stop
======================================================================

Waiting for callbacks...
```

#### 配置 Tavily MCP：

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "http://localhost:3000/tavily-usage",
    "USAGE_REPORT_INTERVAL": "60"
  }
}
```

#### 查看回调消息的三种方式：

**1. 终端控制台（实时）**

接收到回调时，终端会显示彩色输出：

```
======================================================================
📬 Webhook Received!
⏰ Time: 2025-12-17T03:20:00Z
🔔 Event: periodic_report
======================================================================

📊 Periodic Usage Report:
  Total Requests: 150
  Successful: 145
  Failed: 5
  Request Types:
    • Search: 100
    • Extract: 30
    • Crawl: 15
    • Map: 5

Full Payload:
  {
    "timestamp": "2025-12-17T03:20:00Z",
    "event": "periodic_report",
    ...
  }
======================================================================

💾 Saved to webhook-logs.json
📝 Total callbacks received: 1
```

**2. Web 仪表板（浏览器）**

打开浏览器访问：http://localhost:3000/

你会看到一个美观的网页仪表板，显示：
- 📊 接收到的回调总数
- 📝 最近 10 条回调消息
- 🎨 不同事件类型的彩色标签

**3. 日志文件**

所有回调消息自动保存在 `webhook-logs.json`：

```json
{
  "callbacks": [
    {
      "timestamp": "2025-12-17T03:20:00Z",
      "event": "periodic_report",
      "data": {
        "timestamp": "2025-12-17T03:20:00Z",
        "event": "periodic_report",
        "stats": { ... }
      }
    }
  ]
}
```

**优点：**
- ✅ 完全本地，数据私密
- ✅ 多种查看方式
- ✅ 自动保存历史记录
- ✅ 彩色终端输出
- ✅ Web 仪表板

**缺点：**
- ❌ 需要保持服务器运行
- ❌ 仅本地访问（不过可以配置端口转发）

---

### 方式 3: 集成到现有系统

如果你已有后端系统，可以创建一个接收端点：

#### Node.js/Express 示例：

```javascript
app.post('/tavily-webhook', (req, res) => {
  const { event, stats, quotaInfo, alertDetails } = req.body;
  
  console.log('Received Tavily callback:', event);
  
  // 处理不同类型的事件
  switch(event) {
    case 'periodic_report':
      // 保存到数据库或发送通知
      saveToDatabase(stats);
      break;
      
    case 'error_spike':
      // 发送告警邮件或 Slack 消息
      sendAlert(alertDetails);
      break;
      
    case 'quota_alert':
      // 通知管理员
      notifyAdmin(quotaInfo);
      break;
  }
  
  res.json({ status: 'received' });
});
```

#### 配置：

```json
{
  "USAGE_CALLBACK_URL": "https://your-domain.com/tavily-webhook"
}
```

---

## 📡 回调消息格式

### 1. 定期报告（periodic_report）

```json
{
  "timestamp": "2025-12-17T03:20:00Z",
  "event": "periodic_report",
  "stats": {
    "totalRequests": 150,
    "successfulRequests": 145,
    "failedRequests": 5,
    "requestsByType": {
      "search": 100,
      "extract": 30,
      "crawl": 15,
      "map": 5
    },
    "dailyStats": [...],
    "monthlyStats": [...]
  }
}
```

### 2. 错误激增告警（error_spike）

```json
{
  "timestamp": "2025-12-17T03:20:00Z",
  "event": "error_spike",
  "stats": { ... },
  "alertDetails": {
    "message": "High error rate detected: 85.50%",
    "severity": "critical",
    "threshold": 80,
    "currentValue": 85.5
  }
}
```

### 3. 配额告警（quota_alert）

```json
{
  "timestamp": "2025-12-17T03:20:00Z",
  "event": "quota_alert",
  "stats": { ... },
  "quotaInfo": [
    {
      "api_key": "tvly-...",
      "plan": "Pro",
      "usage": {
        "requests": 9500,
        "requests_limit": 10000,
        "requests_remaining": 500
      },
      "billing_period": {
        "start": "2025-12-01",
        "end": "2025-12-31"
      }
    }
  ],
  "alertDetails": {
    "message": "1 API key(s) approaching quota limit",
    "severity": "warning"
  }
}
```

---

## 🔧 完整配置示例

### 使用本地接收器：

```json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "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",
        "USAGE_TRACKING_ENABLED": "true",
        "USAGE_STATS_FILE": "./tavily-usage-stats.json",
        "USAGE_CALLBACK_URL": "http://localhost:3000/tavily-usage",
        "USAGE_REPORT_INTERVAL": "3600",
        "USAGE_ALERT_THRESHOLD": "80"
      }
    }
  }
}
```

### 使用 Slack Webhook：

```json
{
  "env": {
    "USAGE_CALLBACK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  }
}
```

### 使用 Discord Webhook：

```json
{
  "env": {
    "USAGE_CALLBACK_URL": "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
  }
}
```

---

## 💡 实际使用场景

### 场景 1: 实时监控（开发环境）

1. 启动 webhook 接收器：`node webhook-receiver.js`
2. 配置 60 秒的报告间隔
3. 在终端查看实时回调
4. 在浏览器查看历史记录

### 场景 2: 生产环境告警

1. 配置较高的报告间隔（如 3600 秒）
2. 设置告警阈值（如 80%）
3. 将回调发送到 Slack/Discord
4. 仅在出现问题时接收通知

### 场景 3: 数据分析

1. 配置定期报告
2. 将回调保存到数据库
3. 使用 BI 工具分析使用趋势
4. 优化 API 使用策略

---

## 🔍 调试技巧

### 检查回调是否发送：

查看 Tavily MCP 服务器日志：
```
Usage callback sent: periodic_report
```

或错误信息：
```
Failed to send usage callback: ECONNREFUSED
```

### 测试回调端点：

使用 curl 手动发送测试请求：

```bash
curl -X POST http://localhost:3000/tavily-usage \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2025-12-17T03:20:00Z",
    "event": "periodic_report",
    "stats": {
      "totalRequests": 100,
      "successfulRequests": 95,
      "failedRequests": 5,
      "requestsByType": {
        "search": 60,
        "extract": 25,
        "crawl": 10,
        "map": 5
      }
    }
  }'
```

---

## 📚 常见问题

**Q: 回调消息没有收到？**

A: 检查：
1. `USAGE_CALLBACK_URL` 配置正确
2. Webhook 接收器正在运行
3. 防火墙没有阻止连接
4. `USAGE_TRACKING_ENABLED` 设置为 `true`

**Q: 多久收到一次回调？**

A: 取决于配置：
- `USAGE_REPORT_INTERVAL`：定期报告间隔
- 错误率超过阈值时：立即发送
- 配额接近限制时：立即发送

**Q: 可以同时发送到多个 URL 吗？**

A: 目前仅支持一个 URL。如需多个目标，可以创建一个中转服务来分发。

**Q: 回调失败会怎样？**

A: 服务器会记录错误日志，但不会影响 API 调用。统计数据仍会保存到本地文件。

---

## ✅ 快速开始

**最简单的方式：**

1. 打开新终端，运行：
   ```bash
   node webhook-receiver.js
   ```

2. 配置 MCP 客户端：
   ```json
   {
     "USAGE_CALLBACK_URL": "http://localhost:3000/tavily-usage",
     "USAGE_REPORT_INTERVAL": "60"
   }
   ```

3. 使用 Tavily MCP 工具发起几次搜索

4. 在终端或浏览器（http://localhost:3000/）查看回调消息

就这么简单！🎉