Webhooks

Een endpoint registreren

Als u liever wordt aangeroepen dan een socket open te houden, registreer dan een HTTPS-endpoint. We POSTen elke overeenkomende gebeurtenis als dezelfde JSON-envelop, ondertekend met HMAC-SHA256 over de ruwe body in X-XSF-Signature.

registreren — het geheim wordt één keer getoond

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

Een levering verifiëren

Verifieer over de ruwe body. Het opnieuw serialiseren van de geparseerde JSON verandert de bytes en de handtekening zal nooit overeenkomen. Lees de body als bytes voordat iets anders hem aanraakt.

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

Nieuwe pogingen en herstel

We proberen het drie keer opnieuw bij een niet-2xx of een time-out, en laten die levering daarna vallen. Niets blijft eeuwig in de wachtrij. Als uw endpoint niet bereikbaar was, neem dan de laatste sid die u hebt opgeslagen en haal de achterstand in met GET /v1/events of een WebSocket met replay — dat, en niet het herhaalbeleid, is het echte herstelpad.