Webhook

注册端点

如果你宁愿被调用而不是保持一条连接，可以注册一个 HTTPS 端点。我们会把每个匹配的事件以同样的 JSON 信封 POST 过去，并在 X-XSF-Signature 中附上对原始请求体做 HMAC-SHA256 的签名。

curl -X PUT https://api.xsignalfeed.com/v1/account/webhook \
  -H "Authorization: Bearer xsf_your_key" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/xsf"}'

校验投递

对原始请求体做校验。 把解析后的 JSON 重新序列化会改变字节，签名永远对不上。在任何东西碰到请求体之前，先以字节形式读取它。

import hmac, hashlib

def valid(raw_body: bytes, signature: str, secret: str) -> bool:
    want = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, signature)

import { createHmac, timingSafeEqual } from "crypto";

function valid(rawBody, signature, secret) {
  const want = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(want), Buffer.from(signature));
}

mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
ok := hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(signature))

重试与恢复

遇到非 2xx 或超时我们会重试三次，然后放弃该次投递。没有什么会被永久排队。如果你的端点当时宕机了，取出你保存的最后一个 sid，用 GET /v1/events 或带回放的 WebSocket 补齐——真正的恢复路径是这个，而不是重试策略。