StaticResources/docs/Webhook.md · 小枫/XQFChat

# XQFChat Webhook 接收端数据格式

[点击查看API文档](API_V1.md)

## Webhook 概述

当聊天室中发生特定事件时，系统会向已订阅该事件的机器人 Webhook URL 发送 POST 请求。机器人需要正确解析这些数据并返回适当的响应。

## 通用 Webhook 请求格式

### 请求头
```http
POST /webhook-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: XQFChat Webhook/系统版本号
```

### 请求体格式
```json
{
  "event_type": "message.create",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    // 事件具体数据
  },
  "sender_info": {
    "id": 456,
    "nickname": "用户昵称",
    "avatar_url": "https://avatar.url",
    "user_type": "user"
  }
}
```

## 具体事件类型的数据格式

### 1. 消息创建事件 (message.create)

**触发条件**: 用户发送新消息时

```json
{
  "event_type": "message.create",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "message_id": 789,
    "user_id": 456,
    "content": "Hello, world!",
    "message_type": "text",
    "reply_to": null,
    "created_at": 1630000000
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

**消息类型说明**:
- `text`: 纯文本消息
- `markdown`: Markdown格式消息
- `card.file`: 文件卡片消息
- `card.forward`: 转发卡片消息

### 2. 用户加入事件 (user.join)

**触发条件**: 用户加入聊天室时

```json
{
  "event_type": "user.join",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "user_id": 456,
    "room_id": 123,
    "action": "join",
    "joined_at": 1630000000
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

### 3. 用户离开事件 (user.leave)

**触发条件**: 用户离开聊天室时

```json
{
  "event_type": "user.leave",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "user_id": 456,
    "room_id": 123,
    "action": "leave",
    "is_room_deleted": false
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

### 4. 用户被踢出事件 (user.kick)

**触发条件**: 用户被管理员踢出聊天室时

```json
{
  "event_type": "user.kick",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "target_user_id": 456,
    "kicked_by": 789,
    "reason": "违反群规",
    "kicked_at": 1630000000
  },
  "sender_info": {
    "id": 789,
    "nickname": "Admin",
    "avatar_url": "https://avatar.url/admin.jpg",
    "user_type": "user"
  }
}
```

### 5. 聊天室更新事件 (room.update)

**触发条件**: 聊天室信息被更新时

```json
{
  "event_type": "room.update",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "room_id": 123,
    "updated_fields": ["name", "description"],
    "old_data": {
      "name": "旧聊天室名称",
      "description": "旧描述"
    },
    "new_data": {
      "name": "新聊天室名称",
      "description": "新描述"
    }
  },
  "sender_info": {
    "id": 789,
    "nickname": "Admin",
    "avatar_url": "https://avatar.url/admin.jpg",
    "user_type": "user"
  }
}
```

## 特殊消息类型的数据格式

### 文件卡片消息 (card.file)

当消息类型为 `card.file` 时，content 字段包含文件信息：

```json
{
  "event_type": "message.create",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "message_id": 790,
    "user_id": 456,
    "content": {
      "file_id": 55,
      "filename": "example.jpg",
      "file_size": 1024000,
      "file_type": "image",
      "mime_type": "image/jpeg",
      "download_url": "/api/v1/files/download?token=...",
      "uploaded_by": 456
    },
    "message_type": "card.file",
    "reply_to": null,
    "created_at": 1630000000
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

### 转发卡片消息 (card.forward)

当消息类型为 `card.forward` 时，content 字段包含转发信息：

#### 逐条转发模式 (single)
```json
{
  "event_type": "message.create",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "message_id": 791,
    "user_id": 456,
    "content": {
      "mode": "single",
      "source_room_id": 122,
      "original": {
        "id": 1001,
        "user_id": 999,
        "nickname": "OriginalSender",
        "avatar_url": "https://avatar.url/original.jpg",
        "message_type": "text",
        "content": "原始消息内容",
        "created_at": 1629990000
      }
    },
    "message_type": "card.forward",
    "reply_to": null,
    "created_at": 1630000000
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

#### 合并转发模式 (merged)
```json
{
  "event_type": "message.create",
  "timestamp": 1630000000,
  "room_id": 123,
  "data": {
    "message_id": 792,
    "user_id": 456,
    "content": {
      "mode": "merged",
      "source_room_id": 122,
      "count": 3,
      "messages": [
        {
          "id": 1001,
          "user_id": 999,
          "nickname": "User1",
          "avatar_url": "https://avatar.url/user1.jpg",
          "message_type": "text",
          "content": "第一条消息",
          "created_at": 1629990000
        },
        {
          "id": 1002,
          "user_id": 998,
          "nickname": "User2",
          "avatar_url": "https://avatar.url/user2.jpg",
          "message_type": "text",
          "content": "第二条消息",
          "created_at": 1629990100
        }
      ]
    },
    "message_type": "card.forward",
    "reply_to": null,
    "created_at": 1630000000
  },
  "sender_info": {
    "id": 456,
    "nickname": "Alice",
    "avatar_url": "https://avatar.url/alice.jpg",
    "user_type": "user"
  }
}
```

## Webhook 响应要求

### 成功响应
Webhook 接收端应该在 5 秒内返回 HTTP 200 状态码：

```http
HTTP/1.1 200 OK
Content-Type: application/json
```

```json
{
  "status": "success",
  "message": "Webhook processed successfully"
}
```

### 错误响应
如果处理失败，可以返回相应的错误信息：

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
```

```json
{
  "status": "error",
  "message": "Invalid request format",
  "code": "INVALID_FORMAT"
}
```

### 2. IP 白名单
建议 Webhook 接收端验证请求来源 IP，确保只接受来自聊天系统服务器的请求。

## Webhook 重试机制

系统会对失败的 Webhook 请求进行重试：

- **重试间隔**: 指数退避策略（1s, 5s, 30s, 5m, 30m, 2h）
- **最大重试次数**: 6 次
- **超时时间**: 10 秒

## 最佳实践

### 1. 处理幂等性
由于重试机制，同一个 Webhook 可能会被多次发送，接收端应该处理重复请求：

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

### 2. 异步处理
对于耗时的操作，建议先立即返回 200 响应，然后异步处理：

```javascript
app.post('/webhook', (req, res) => {
  // 立即响应
  res.status(200).json({ status: 'success' });
  
  // 异步处理
  processWebhookAsync(req.body).catch(console.error);
});
```

### 3. 错误日志记录
记录详细的错误信息以便调试：

```javascript
function processWebhook(event) {
  try {
    // 处理逻辑
  } catch (error) {
    console.error('Webhook processing failed:', {
      event_type: event.event_type,
      room_id: event.room_id,
      error: error.message,
      stack: error.stack,
      timestamp: new Date().toISOString()
    });
    throw error;
  }
}
```

## 示例 Webhook 接收端实现

### Node.js 示例
```javascript
const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {  
  const event = req.body;
  
  try {
    // 根据事件类型处理
    switch (event.event_type) {
      case 'message.create':
        handleMessageCreate(event);
        break;
      case 'user.join':
        handleUserJoin(event);
        break;
      case 'user.leave':
        handleUserLeave(event);
        break;
      default:
        console.log('Unhandled event type:', event.event_type);
    }
    
    // 成功响应
    res.json({ 
      status: 'success', 
      message: 'Event processed successfully' 
    });
    
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ 
      status: 'error', 
      message: 'Internal server error' 
    });
  }
});

function handleMessageCreate(event) {
  const { room_id, data, sender_info } = event;
  
  console.log(`New message in room ${room_id}:`, {
    message_id: data.message_id,
    content: data.content,
    sender: sender_info.nickname,
    message_type: data.message_type
  });
  
  // 在这里添加机器人的响应逻辑
  // 例如：关键词回复、自动翻译等
}

function handleUserJoin(event) {
  const { room_id, data, sender_info } = event;
  
  console.log(`User joined room ${room_id}:`, {
    user_id: data.user_id,
    user_name: sender_info.nickname
  });
  
  // 发送欢迎消息等
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook receiver listening on port ${PORT}`);
});
```

这个 Webhook 系统设计确保了机器人能够及时响应聊天室中的各种事件，同时提供了完善的安全机制和错误处理。

小枫/XQFChat

About

Releases (1)

Contributors

Language(Optional)

Activities