Webhooks

Einen Endpunkt registrieren

Wenn Sie lieber aufgerufen werden, statt einen Socket zu halten, registrieren Sie einen HTTPS-Endpunkt. Wir senden jedes passende Ereignis per POST als denselben JSON-Umschlag, signiert mit HMAC-SHA256 über den rohen Body in X-XSF-Signature.

registrieren – das Secret wird nur einmal angezeigt

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"}'

Eine Zustellung prüfen

Prüfen Sie über den rohen Body. Das erneute Serialisieren des geparsten JSON verändert die Bytes, und die Signatur wird nie passen. Lesen Sie den Body als Bytes, bevor irgendetwas anderes ihn anfasst.

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))

Wiederholungen und Wiederherstellung

Bei einem Nicht-2xx oder einem Timeout versuchen wir es dreimal erneut und verwerfen dann diese Zustellung. Nichts wird ewig in der Warteschlange gehalten. War Ihr Endpunkt nicht erreichbar, nehmen Sie die letzte gespeicherte sid und holen Sie mit GET /v1/events oder einem nachspielenden WebSocket auf – das, nicht die Retry-Richtlinie, ist der eigentliche Wiederherstellungspfad.