Webhook

当关注的站点发生可用性变化、价格波动，或发现更便宜的替代分组时，中转神探会向您设置的 Webhook URL 发送 JSON 格式的事件请求。
Webhook 面向所有用户免费开放，仅以少量积分消耗限制滥用。

本文介绍接收要求、事件类型、请求体结构和签名校验。回调地址与订阅范围可在个人中心 → Webhook设置。

接收说明

触发范围：当您订阅的站点或分组触发已启用的事件时，中转神探会向对应回调地址发送通知。
请求格式：每条通知均为 HTTP POST 请求，请求体使用 JSON 格式，具体字段见下方说明。
成功响应：接收服务应在设定的超时时间内返回 2xx 状态码；超时或返回其他状态码会被视为发送失败，并按您的配置重试。
安全校验：建议先完成签名校验，再解析和处理事件内容，以确认请求来自中转神探且传输内容未被篡改。
接入检查：首次配置或调整接收服务后，可发送测试事件，并在 Webhook 管理页查看最近的成功或失败结果。

事件类型

事件	触发条件	请求参数	单价
network_outage	站点网络层连续不可达，超过容错窗口	可用性事件	100积分/万次
network_recovery	站点网络层由故障恢复	可用性事件	100积分/万次
ai_outage	站点 AI 接口持续不可用，超过容错窗口（默认 5 分钟）	可用性事件	100积分/万次
ai_recovery	站点 AI 接口由故障恢复	可用性事件	100积分/万次
price_increase	关注分组的计价倍率上涨，达到设定的绝对阈值	价格事件	100积分/万次
price_decrease	关注分组的计价倍率下跌，达到设定的绝对阈值	价格事件	100积分/万次
alternative_group	发现更便宜的跨站同类替代分组（不同站点、倍率更低、主力模型有交集）	替代分组事件	100积分/万次
webhook.test	在配置页手动触发，用于联调接收端	测试事件	100积分/万次

请求体结构

每次回调都会发送 JSON 格式请求体，其中包含以下公共字段：

字段	类型	说明
event	string	事件类型（见上表）
site_id	int	站点 ID。订阅事件固定为 0（真实站点见 data.site_id）；测试事件 webhook.test 为真实站点 ID
timestamp	int	事件发生的 Unix 时间戳（秒）
data	object	事件数据，结构因事件而异（见下）
group_id	int?	分组 ID。仅分组级事件携带

事件请求参数

可用性事件network_outage / network_recovery / ai_outage / ai_recovery

字段	类型	说明
site_id	int	站点 ID
site_name	string	站点名称
title	string	事件标题
content	string	事件描述

签名校验（HMAC-SHA256）

中转神探在每个回调请求的请求头中携带 X-Zzstan-Signature，该值由签名密钥和未经解析的请求体计算得到。接收端按以下步骤完成签名校验：

在「个人中心 → Webhook」配置回调 URL 并保存，获取自动生成的签名密钥（dcwh_ 开头）。
接收请求后，先读取未经解析的原始请求体；签名校验通过前不要解析 JSON。
取请求头 X-Zzstan-Signature 的值。
使用签名密钥和原始请求体计算 HMAC-SHA256，输出十六进制字符串作为期望签名。
使用常量时间比较期望签名与请求头；两者一致时继续处理，否则拒绝请求。

接收与签名校验示例

以下示例演示如何接收请求、完成签名校验并解析事件。请将 APP_SECRET 替换为您的签名密钥。

from fastapi import FastAPI, Request, HTTPException
import hmac
import hashlib

APP_SECRET = "dcwh_your_secret"
app = FastAPI()


@app.post("/webhook")
async def webhook(request: Request):
    raw = await request.body()
    signature = request.headers.get("X-Zzstan-Signature", "")
    expected = hmac.new(
        APP_SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(signature, expected):
        raise HTTPException(status_code=401, detail="invalid signature")

    payload = await request.json()
    event = payload["event"]      # 事件类型
    data = payload["data"]        # 事件数据
    # ...按 event 处理 data...
    return {"ok": True}

完整请求示例

{
  "event": "ai_outage",
  "site_id": 0,
  "timestamp": 1719000000,
  "data": {
    "site_id": 1001,
    "site_name": "示例中转站",
    "title": "示例中转站 AI 不可用",
    "content": "检测到 AI 接口持续不可用，已超过 5 分钟容错窗口。",
    "status": "outage"
  },
  "group_id": 2001
}

价格事件price_increase / price_decrease

字段	类型	说明
site_id	int	站点 ID
site_name	string	站点名称
channel_name	string	分组（渠道）名称
title	string	事件标题
content	string	事件描述
baseline_ratio	float	基线倍率（本次波动前的参考值）
current_ratio	float	当前倍率
delta	float	达到的绝对阈值（baseline → current 的变化量）

完整请求示例

{
  "event": "price_increase",
  "site_id": 0,
  "timestamp": 1719000000,
  "data": {
    "site_id": 1001,
    "site_name": "示例中转站",
    "channel_name": "Claude 专线",
    "title": "示例中转站 / Claude 专线 倍率上涨",
    "content": "倍率从基线 1.5 上涨到 1.8，已达到您设置的绝对阈值 0.3。",
    "baseline_ratio": 1.5,
    "current_ratio": 1.8,
    "delta": 0.3
  },
  "group_id": 2001
}

替代分组事件alternative_group

字段	类型	说明
site_id	int	新替代分组所在站点 ID
site_name	string	新替代分组所在站点名称
new_group_id	int	新替代分组 ID
title	string	事件标题
content	string	事件描述
new_ratio	float	新替代分组倍率（更便宜）
sub_ratio	float	您已关注分组的倍率（被替代方）

完整请求示例

{
  "event": "alternative_group",
  "site_id": 0,
  "timestamp": 1719000000,
  "data": {
    "site_id": 1002,
    "site_name": "另一中转站",
    "new_group_id": 3001,
    "title": "发现更便宜的替代分组",
    "content": "另一中转站 / GPT 通道 提供同类模型，倍率 1.2 低于您关注的 1.5。",
    "new_ratio": 1.2,
    "sub_ratio": 1.5
  },
  "group_id": 2001
}

测试事件webhook.test

字段	类型	说明
message	string	固定文案：中转神探 Webhook 测试
group_id	int?	分组 ID（用户级分组目标测试时携带）

完整请求示例

{
  "event": "webhook.test",
  "site_id": 1001,
  "timestamp": 1719000000,
  "data": {
    "message": "中转神探 Webhook 测试",
    "group_id": 2001
  },
  "group_id": 2001
}

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态

站点	站点分组	人气	倍率	倍率变动	掺水率	延迟	7天可用率	可用状态