웹훅

엔드포인트 등록

소켓을 유지하는 대신 호출받기를 원한다면 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가 아닌 응답이나 타임아웃이 발생하면 세 번 재시도한 뒤 해당 전달을 포기합니다. 영원히 큐에 남는 것은 없습니다. 엔드포인트가 다운되었다면 마지막으로 저장한 sid를 가지고 GET /v1/events나 리플레이하는 WebSocket으로 따라잡으십시오. 재시도 정책이 아니라 그것이 진짜 복구 경로입니다.