Webhook

エンドポイントを登録する

ソケットを保持するより呼び出してもらいたい場合は、HTTPS エンドポイントを登録してください。マッチした各イベントを同じ JSON エンベロープで POST し、生のボディに対する HMAC-SHA256 署名を X-XSF-Signature に付けます。

登録 — シークレットは一度しか表示されません

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 以外またはタイムアウトの場合は 3 回リトライし、その後その配信は破棄します。永遠にキューに残るものはありません。エンドポイントがダウンしていた場合は、最後に保存した sid を使って GET /v1/events またはリプレイ付きの WebSocket で追いついてください。本当の復旧経路はリトライポリシーではなくそちらです。