Webhooks

Enregistrer un point de terminaison

Si vous préférez être appelé plutôt que de maintenir un socket, enregistrez un point de terminaison HTTPS. Nous envoyons chaque événement correspondant en POST, dans la même enveloppe JSON, signée en HMAC-SHA256 sur le corps brut dans X-XSF-Signature.

enregistrement — le secret n'est affiché qu'une fois

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

Vérifier une livraison

Vérifiez sur le corps brut. Resérialiser le JSON analysé change les octets et la signature ne correspondra jamais. Lisez le corps en octets avant que quoi que ce soit d'autre n'y touche.

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

Nouvelles tentatives et récupération

Nous réessayons trois fois sur une réponse non-2xx ou un délai dépassé, puis abandonnons cette livraison. Rien n'est mis en file d'attente indéfiniment. Si votre point de terminaison était hors service, prenez le dernier sid que vous avez stocké et rattrapez le retard avec GET /v1/events ou un WebSocket en rejeu — c'est cela, et non la politique de réessai, le véritable chemin de récupération.