指南

Webhook 指南

有公网 HTTPS 时优先用 Webhook；与 getUpdates 互斥。

适用场景

机器人服务可被公网访问时用 Webhook：平台主动 POST Update，延迟低、无需本机长轮询。本地调试无公网时改用长轮询。

步骤

准备可公网访问的 https:// 地址（自签证书通常不可用）。
在控制台 → 机器人 → Webhook 填写 URL 与 secret_token，或调 POST /api/v1/bots/setWebhook。
验签（V2）：头 X-StarIM-Signature-V2: sha256=<hex>、X-StarIM-Timestamp（秒）；签名内容为 HMAC-SHA256(secret, timestamp + "." + rawBody)。幂等键看 X-StarIM-Update-Id。SDK 默认允许时间戳窗口约 ±300s。
在控制台「投递日志」确认 success；失败可重试，dead_letter 需排查后手动重投。

示例

curl -X POST "$API/bots/setWebhook" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","secret_token":"your-secret"}'

约束与错误

与 getUpdates 互斥：已挂 Webhook 再调长轮询 → 409 Conflict。
投递超时 15s；失败按 1m / 5m / 15m / 1h 重试，最终 dead_letter。
出站 IP：GET /api/v1/bots/getWebhookInfo → platform_egress_ips。

Node 不要先 express.json() 再验签。官方 SDK 提供 webhookCallback() / 验签中间件。

下一步

看 Webhook API、Update 事件；配置入口在控制台 Webhook 面板。