Open Platform
统计回调（Webhook）
ProxyCast Connect 提供统计回调机制，让中转商追踪推广效果。
统计回调（Webhook）
ProxyCast Connect 提供统计回调机制，让中转商追踪推广效果。
回调流程
用户点击一键配置
│
▼
ProxyCast 打开，显示确认弹窗
│
├─── 用户取消 ───▶ 发送回调: status=cancelled
│
└─── 用户确认 ───▶ Key 添加成功
│
▼
发送回调: status=success
│
▼
中转商收到回调，更新统计
配置回调
在 providers/{id}.json 中添加 webhook 配置：
{
"id": "myrelay",
"name": "我的中转站",
"webhook": {
"callback_url": "https://api.myrelay.com/proxycast/callback"
}
}
| 字段 | 必填 | 说明 |
|---|---|---|
webhook.callback_url | ✅ | 回调地址（必须 HTTPS） |
回调请求格式
ProxyCast 向中转商发送 POST 请求：
POST https://api.myrelay.com/proxycast/callback
Content-Type: application/json
User-Agent: ProxyCast/1.2.0
{
"event": "connect",
"status": "success",
"relay_id": "myrelay",
"ref": "promo2024",
"key_prefix": "sk-xxxx",
"timestamp": "2026-01-05T12:00:00Z",
"client": {
"version": "1.2.0",
"platform": "macos"
}
}
回调字段说明
| 字段 | 说明 |
|---|---|
event | 事件类型：connect |
status | 状态：success（成功）、cancelled（用户取消）、error（失败） |
relay_id | 中转商 ID |
ref | 推广码（如果有） |
key_prefix | Key 前缀（脱敏，仅前 7 位） |
timestamp | 事件时间（ISO 8601 格式） |
client.version | ProxyCast 版本 |
client.platform | 平台：macos、windows、linux |
error_code | 错误码（仅 status=error 时） |
error_message | 错误信息（仅 status=error 时） |
请求验证
由于 ProxyCast 是开源软件，不使用签名验证。中转商应通过以下方式验证请求：
- 检查 key_prefix - 验证该 Key 前缀是否为自己下发的 Key
- 检查 relay_id - 确认是自己的中转商 ID
- 检查 User-Agent - 确认包含
ProxyCast
Express 示例
app.post('/proxycast/callback', async (req, res) => {
const { relay_id, key_prefix, status, ref } = req.body;
const userAgent = req.headers['user-agent'] || '';
// 验证 User-Agent
if (!userAgent.includes('ProxyCast')) {
return res.status(403).json({ error: 'Invalid User-Agent' });
}
// 验证 relay_id
if (relay_id !== 'myrelay') {
return res.status(403).json({ error: 'Invalid relay_id' });
}
// 验证 key_prefix 是否为自己下发的 Key
const isValidKey = await db.apiKeys.exists({
key: { $regex: `^${key_prefix}` }
});
if (!isValidKey) {
return res.status(403).json({ error: 'Unknown key_prefix' });
}
// 处理回调
if (status === 'success') {
await db.stats.increment({
relay_id,
ref: ref || 'direct',
date: new Date().toISOString().split('T')[0]
});
}
res.json({ received: true });
});
重试机制
| 重试次数 | 间隔 | 说明 |
|---|---|---|
| 第 1 次 | 立即 | 首次发送 |
| 第 2 次 | 1 分钟 | 首次失败后 |
| 第 3 次 | 5 分钟 | 第二次失败后 |
| 第 4 次 | 30 分钟 | 第三次失败后 |
| 放弃 | - | 超过 4 次不再重试 |
成功响应：HTTP 2xx 状态码
统计数据示例
基于回调数据，中转商可以构建统计面板：
┌─────────────────────────────────────────────────────────────┐
│ ProxyCast Connect 统计 2026-01-05 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 今日概览 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 128 │ │ 115 │ │ 13 │ │ 89.8% │ │
│ │ 点击次数 │ │ 成功配置 │ │ 用户取消 │ │ 转化率 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ 推广码效果 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 推广码 点击 成功 取消 转化率 │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ promo2024 56 52 4 92.9% │ │
│ │ twitter 38 33 5 86.8% │ │
│ │ (无推广码) 34 30 4 88.2% │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
隐私保护
回调数据遵循最小化原则：
| 数据 | 是否发送 | 说明 |
|---|---|---|
| 完整 API Key | ❌ | 仅发送前 7 位前缀 |
| 用户 ID | ❌ | 不发送任何用户标识 |
| 设备 ID | ❌ | 不发送设备标识 |
| IP 地址 | ❌ | 不发送用户 IP |
| 推广码 | ✅ | 用于统计推广效果 |
| 平台信息 | ✅ | 仅操作系统类型 |
错误码
当 status=error 时，会包含错误信息：
| 错误码 | 说明 |
|---|---|
invalid_relay | 中转商 ID 无效 |
invalid_key | API Key 格式无效 |
relay_not_found | 中转商未注册 |
network_error | 网络错误 |
internal_error | 内部错误 |
最佳实践
- 验证 key_prefix - 检查是否为自己下发的 Key
- 幂等处理 - 同一事件可能重复发送
- 快速响应 - 在 5 秒内返回响应
- 异步处理 - 复杂逻辑放到后台队列