GEO webhook 的价值

Webhook 允许 GEO 体检仪在特定事件发生时主动通知你的系统，实现实时集成，参考GEO API：

• 实时性：事件发生即刻推送，无需轮询
• 自动化：触发内部系统自动化流程
• 低延迟：相比定时拉取，延迟更低
• 省资源：无需持续轮询 API

webhook 支持的事件类型

事件	触发时机	用途
diagnose.completed	诊断完成	自动拉取报告/通知团队
alert.mention_drop	提及率下降预警	触发应急优化流程
alert.competitor_overtake	竞品反超预警	通知管理层
alert.negative_sentiment	负面描述预警	触发危机公关
report.monthly_ready	月度报告生成	自动分发报告

webhook 配置流程（年度套餐）

Step 1: 设置回调 URL

• 在你的服务端准备一个可接收 POST 请求的 URL
• URL 必须为 HTTPS（生产环境）
• 确保 URL 可公网访问

Step 2: 选择触发事件

根据需求选择要订阅的事件类型，建议：

• 诊断完成（必选）
• 所有预警事件（必选）
• 月度报告就绪（推荐）

Step 3: 配置签名验证

为防止伪造请求，GEO 体检仪对 webhook 请求签名：

• 每个 webhook 配置有一个 secret
• 请求头含 X-GEO-Signature，值为 HMAC-SHA256 签名
• 你的服务端应验证签名，确认请求来自 GEO 体检仪

Step 4: 测试 webhook

配置完成后，点击「发送测试事件」验证：

1. GEO 体检仪发送测试事件到你的 URL
2. 你的服务端应返回 200 状态码
3. 确认能正确解析请求体

webhook 请求格式

POST <your_url>
Content-Type: application/json
X-GEO-Signature: <HMAC-SHA256 signature>

{
  "event": "diagnose.completed",
  "timestamp": "2026-07-01T10:30:00Z",
  "data": {
    "diagnose_id": "diag_xxx",
    "brand": "品牌名",
    "overall_score": 78,
    "report_url": "https://..."
  }
}

webhook 处理的最佳实践

1. 及时响应

收到 webhook 后立即返回 200，耗时操作异步处理：

// Node.js 示例
app.post('/geo-webhook', (req, res) => {
  // 验证签名
  if (!verifySignature(req)) return res.status(401).send();
  // 立即返回 200
  res.status(200).send();
  // 异步处理
  processEvent(req.body);
});

2. 幂等处理

同一事件可能推送多次，你的系统应幂等处理：

• 用 event_id 去重
• 已处理的事件直接返回 200

3. 错误重试

GEO 体检仪的重试策略：

• 首次推送失败后，重试 3 次（间隔 1/5/30 分钟）
• 连续失败 3 次后暂停推送，需手动恢复
• 你的服务端恢复后可手动触发重试

webhook vs API 轮询

方式	实时性	资源消耗	实现复杂度
Webhook	实时	低（被动接收）	中（需服务端接收）
API 轮询	延迟（轮询间隔）	高（持续请求）	低（主动请求）

建议：关键事件用 webhook，历史数据用 API 轮询。参考GEO 自动化。