事件推送（webhook）

账号侧的动态（新评论、评论删除/隐藏、私信收发、发布状态变化）可以主动推送到你的服务，无需轮询。消费语义与订阅规则见事件推送规则。

开通

方式一：webhook 公网推送（生产推荐）

1. POST /v1/webhook-endpoints 创建接收端点（公网 https 地址）：

// 请求
{ "url": "https://your-server.com/webhooks/haina", "eventTypes": ["*"] }
// 响应（secret 只出现这一次，请立即保存）
{ "code": 0, "data": { "id": "…", "url": "…", "eventTypes": ["*"], "secret": "vgwh_…" } }

2. 保存好 secret——它用于校验推送请求的签名。eventTypes 填 ["*"] 接收全部事件，["tiktok.*"] 接收 TikTok 全平台事件，或精确订阅（如 ["tiktok.message.received", "tiktok.comment.created"]）。

方式二：listen 本地监听（无需公网地址，开发/本机场景）

haina listen --events tiktok.comment.created --forward-to http://localhost:8080/webhooks/haina

CLI 用 API Token 建立出站 SSE 长连（GET /v1/events/stream），事件实时推下来：stdout 每事件一行 JSON（与推送体同形状），--forward-to 可同时 POST 转发到本地 handler（loopback 调试不带签名头）。断线自动重连（Last-Event-ID 续传）；只推连接后的新事件，断开期间的用 GET /v1/events 补拉。

推送格式

POST https://your-server.com/webhooks/haina
Content-Type: application/json
X-Vidgate-Signature: t=1760000000,v1=<签名>

{
  "id": "事件唯一 id（幂等键）",
  "platform": "tiktok",
  "type": "tiktok.message.received",          // 归一化事件类型（平台前缀命名空间）
  "event": "im_receive_msg",           // 官方原始事件名
  "occurred_at": "2026-09-18T01:23:45.000Z",  // 事件发生时刻
  "received_at": "2026-09-18T01:23:46.100Z",  // 平台收到时刻（对账用）
  "seat_id": "……",
  "data": { /* 事件内容（字段名与官方文档一致） */ }
}

GET /v1/events 拉取到的事件对象与推送体形状完全一致（同一套 snake_case 字段），push 失败或补漏时按 id 对账即可。

验签（务必做）

// Node.js 示例
const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('='))
  );
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false; // 5 分钟防重放窗
  const key = crypto.createHash('sha256').update(secret).digest('hex');
  const expect = crypto.createHmac('sha256', key).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(v1));
}

做「收到评论自动回复」类机器人的三条军规

1. 只订 tiktok.comment.created（tiktok.comment.deleted / tiktok.comment.visibility_changed 是删除/隐藏动作，回复它们必被官方拒绝）；
2. 只回复 data.parent_comment_id == 0（数字 0）的顶层评论——事件里没有 owner 字段，你自己的回复也是评论事件，靠 parent 判顶楼可避免机器人自回复死循环；
3. 控制频率并保持文案差异（短时间大量同质回复会被平台判 spam）；接收端务必按事件 id 幂等（重试会重复投递）。

调试台（网页）

管理后台的 事件通知 页（左侧导航「接入」分组）提供 Stripe 式调试体验：「订阅设置」里勾选事件类型即可创建 webhook 端点（网页直建，无需先调 API）或生成 listen 命令（含活跃监听连接状态灯）；「事件流」实时查看完整 payload；「投递记录」有每次投递的状态码/耗时/失败原因，失败或任意投递可一键重投（也可 POST /v1/events/{id}/redeliver 或 haina events redeliver <id>）。