Webhooks de notification

Stratum peut envoyer vos événements d'automatisation du financement vers un point de terminaison HTTPS que vous contrôlez (méthode POST). Le webhook est un canal de notification : vous l'activez pour les types d'événements qui vous intéressent, et Stratum livre chacun d'eux sous forme de requête JSON que vous pouvez acheminer vers vos propres outils, alertes ou tableaux de bord. Il s'agit d'un complément aux notifications dans l'application et par e-mail — et non d'un remplacement du modèle de sécurité entourant votre clé API Bitfinex à portée limitée.

1. Activer le canal webhook

La livraison des notifications se configure par type d'événement et par canal. Pour commencer à recevoir des webhooks, envoyez une mise à jour de préférence à PUT /api/v1/settings/notifications avec le corps suivant :

  • type — le type d'événement que vous souhaitez recevoir (voir la liste ci-dessous).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — votre point de terminaison HTTPS (2048 caractères maximum).

Pour voir votre configuration actuelle, GET /api/v1/settings/notifications liste vos préférences explicites, et GET /api/v1/settings/notifications/effective renvoie la vue fusionnée des valeurs par défaut et de vos remplacements à partir de laquelle s'affiche l'écran des paramètres — y compris votre webhookUrl et un indicateur hasWebhookSecret.

2. Exigences pour le point de terminaison

Votre URL doit utiliser https. Stratum valide l'URL à la fois lorsque vous l'enregistrez et de nouveau au moment de la livraison, et rejette les points de terminaison qui pointent vers localhost ou vers des adresses de réseau interne/privé. Les redirections ne sont pas suivies — la requête est envoyée à l'URL exacte que vous avez configurée. Votre point de terminaison doit répondre avec un statut 2xx ; toute autre réponse est considérée comme un échec de livraison et fait l'objet d'une relance.

3. Types d'événements que vous pouvez acheminer

Les types d'événements suivants peuvent être livrés à un webhook :

  • RATE_SPIKE, RATE_DROP, RATE_FLOOR_BLOCKED
  • LOAN_EXECUTED, LOAN_EXPIRING, LOAN_EARLY_REPAID, LARGE_EARLY_REPAYMENT, LARGE_LOAN_FILLED
  • STALE_OFFER
  • KILL_SWITCH_ACTIVATED, STRATEGY_PAUSED, STRATEGY_ERROR, STRATEGY_TICK_STALE
  • API_KEY_INVALID, API_KEY_PERMISSIONS_CHANGED
  • PLATFORM_OUTAGE, PLATFORM_RECOVERED, SYSTEM_ALERT
  • LOW_UTILIZATION, IDLE_CASH, FEE_TIER_CHANGED
  • DAILY_DIGEST, WEEKLY_DIGEST, MONTHLY_DIGEST, YEARLY_DIGEST

Quelques types d'événements ne sont pas activables par canal dans les paramètres — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE et WITHDRAWAL_DETECTED sont gérés automatiquement pour vous et ne sont pas proposés à l'activation par webhook. Les récapitulatifs périodiques (de DAILY_DIGEST à YEARLY_DIGEST) sont envoyés par e-mail par défaut ; activez explicitement le canal webhook si vous souhaitez les recevoir aussi par ce biais.

4. Schéma de payload

Chaque livraison est un objet JSON unique envoyé avec Content-Type: application/json :

  • type — le nom du type d'événement, par ex. LOAN_EXECUTED.
  • severity — l'une des valeurs INFO, WARNING ou ERROR.
  • title — un titre court et lisible.
  • body — un message lisible.
  • createdAt — un instant au format ISO-8601.
  • payload — un objet contenant des champs spécifiques au type ; il peut être vide.
  • userId — votre identifiant utilisateur numérique.

Par exemple (les valeurs des champs ne sont qu'illustratives) :

  • {"type":"LOAN_EXECUTED","severity":"INFO","title":"Loan executed","body":"A funding offer was filled.","createdAt":"2026-05-31T12:00:00Z","payload":{},"userId":1}

5. En-têtes

Chaque requête porte :

  • X-Stratum-Type — le nom du type d'événement (la même valeur que le type du corps).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Lorsque vous disposez d'un secret de signature, chaque requête inclut également X-Stratum-Timestamp et X-Stratum-Signature (voir la vérification de signature ci-dessous).

6. Livraison et relances

Stratum attend jusqu'à 5 secondes que votre point de terminaison réponde. Si une livraison échoue — réponse non-2xx, délai dépassé ou erreur de connexion — elle est relancée avec un backoff exponentiel. Il y a jusqu'à 6 tentatives de livraison au total, avec des délais de 1 minute, 5 minutes, 15 minutes, 1 heure et 4 heures entre les tentatives successives. Un planificateur récupère les relances dues environ toutes les 60 secondes. Concevez votre point de terminaison pour qu'il soit idempotent, afin qu'une livraison relancée du même événement soit sans conséquence.

7. Secret de signature

Les préférences de webhook sont stockées par type d'événement, et chacune porte son propre secret de signature. La première fois que vous activez le canal webhook pour un type d'événement donné, Stratum génère ce secret et le renvoie une seule fois — dans la réponse à cette requête de mise à jour. Enregistrez-le immédiatement. Par la suite, les points de terminaison de liste et de vue effective indiquent uniquement qu'un secret existe pour cette préférence (hasWebhookSecret: true) ; ils ne renvoient jamais la valeur de nouveau, et il n'existe aucun moyen de la récupérer ultérieurement. Les mises à jour ultérieures du même type d'événement réutilisent le secret existant plutôt que d'en générer un nouveau.

8. Vérifier la signature

Utilisez le secret de signature pour confirmer qu'une livraison provient réellement de Stratum et qu'elle n'a pas été altérée ni rejouée. Pour chaque requête signée :

  • Lisez X-Stratum-Timestamp (secondes Unix) et X-Stratum-Signature (au format v1=<hex>).
  • Construisez la chaîne signée en joignant l'horodatage et le corps brut de la requête par un point : <timestamp>.<raw body>.
  • Calculez le HMAC-SHA256 sur cette chaîne en utilisant votre secret comme clé, puis encodez le résultat en hexadécimal.
  • Comparez votre empreinte hexadécimale à la valeur qui suit v1= à l'aide d'une comparaison à temps constant. Rejetez la requête si elle ne correspond pas.
  • Rejetez les requêtes dont l'horodatage est trop ancien pour votre tolérance, afin de vous prémunir contre les rejeux.

Calculez le HMAC sur les octets exacts que vous avez reçus, avant toute re-sérialisation JSON.

En savoir plus

Consultez le démarrage rapide des clés API, l'aperçu de la sécurité, le catalogue de stratégies et le calculateur d'APR pour en savoir plus sur la façon dont Stratum automatise le financement sur marge Bitfinex.