Benachrichtigungs-Webhooks

Stratum kann Ihre Funding-Automatisierungs-Ereignisse per POST an einen HTTPS-Endpunkt senden, den Sie kontrollieren. Der Webhook ist ein Benachrichtigungs-Kanal: Sie aktivieren ihn für die Ereignistypen, die Sie interessieren, und Stratum liefert jeden einzelnen als JSON-Anfrage, die Sie in Ihr eigenes Tooling, Ihre Alerts oder Dashboards leiten können. Dies ist eine Ergänzung zu den In-App- und E-Mail-Benachrichtigungen — kein Ersatz für das Sicherheitsmodell rund um Ihren zugriffsbeschränkten Bitfinex-API-Key.

1. Den Webhook-Kanal aktivieren

Die Benachrichtigungszustellung wird pro Ereignistyp und pro Kanal konfiguriert. Um mit dem Empfang von Webhooks zu beginnen, senden Sie einen Präferenz-Upsert an PUT /api/v1/settings/notifications mit folgendem Body:

  • type — der Ereignistyp, den Sie zugestellt haben möchten (siehe die Liste unten).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — Ihr HTTPS-Endpunkt (maximal 2048 Zeichen).

Um zu sehen, was Sie derzeit konfiguriert haben, listet GET /api/v1/settings/notifications Ihre expliziten Präferenzen auf, und GET /api/v1/settings/notifications/effective liefert die zusammengeführte Ansicht aus Standardwerten plus Overrides, aus der das Einstellungsfenster gerendert wird — einschließlich Ihrer webhookUrl und eines hasWebhookSecret-Flags.

2. Anforderungen an den Endpunkt

Ihre URL muss https verwenden. Stratum validiert die URL sowohl beim Speichern als auch erneut zum Zustellzeitpunkt und lehnt Endpunkte ab, die auf localhost oder interne/private Netzwerkadressen verweisen. Weiterleitungen werden nicht verfolgt — die Anfrage geht an genau die URL, die Sie konfiguriert haben. Ihr Endpunkt sollte mit einem 2xx-Status antworten; jede andere Antwort wird als Zustellungsfehler behandelt und erneut versucht.

3. Ereignistypen, die Sie leiten können

Die folgenden Ereignistypen können an einen Webhook zugestellt werden:

  • 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

Einige Ereignistypen werden in den Einstellungen nicht pro Kanal umgeschaltet — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE und WITHDRAWAL_DETECTED werden für Sie verwaltet und stehen nicht zur Webhook-Anmeldung zur Verfügung. Die periodischen Digests (DAILY_DIGEST bis YEARLY_DIGEST) werden standardmäßig per E-Mail zugestellt; aktivieren Sie den Webhook-Kanal explizit, wenn Sie sie auch dorthin zugestellt haben möchten.

4. Payload-Schema

Jede Zustellung ist ein einzelnes JSON-Objekt, das mit Content-Type: application/json gesendet wird:

  • type — der Name des Ereignistyps, z. B. LOAN_EXECUTED.
  • severity — einer von INFO, WARNING oder ERROR.
  • title — ein kurzer, menschenlesbarer Titel.
  • body — eine menschenlesbare Nachricht.
  • createdAt — ein ISO-8601-Zeitpunkt.
  • payload — ein Objekt mit typspezifischen Feldern; es kann leer sein.
  • userId — Ihre numerische Benutzer-ID.

Zum Beispiel (die Feldwerte dienen nur zur Veranschaulichung):

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

5. Header

Jede Anfrage enthält:

  • X-Stratum-Type — der Name des Ereignistyps (derselbe Wert wie das type im Body).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Wenn Sie ein Signing-Secret haben, enthält jede Anfrage zusätzlich X-Stratum-Timestamp und X-Stratum-Signature (siehe Signaturverifizierung unten).

6. Zustellung und Retries

Stratum wartet bis zu 5 Sekunden auf eine Antwort Ihres Endpunkts. Wenn eine Zustellung fehlschlägt — eine Nicht-2xx-Antwort, ein Timeout oder ein Verbindungsfehler — wird sie mit exponentiellem Backoff erneut versucht. Es gibt insgesamt bis zu 6 Zustellversuche, mit Verzögerungen von 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und 4 Stunden zwischen den aufeinanderfolgenden Versuchen. Ein Scheduler nimmt fällige Retries etwa alle 60 Sekunden auf. Gestalten Sie Ihren Endpunkt idempotent, damit eine erneute Zustellung desselben Ereignisses harmlos ist.

7. Signing-Secret

Webhook-Präferenzen werden pro Ereignistyp gespeichert, und jede trägt ihr eigenes Signing-Secret. Wenn Sie den Webhook-Kanal für einen bestimmten Ereignistyp zum ersten Mal aktivieren, generiert Stratum dieses Secret und gibt es genau einmal zurück — in der Antwort auf diese Upsert-Anfrage. Speichern Sie es sofort. Danach melden die Listen- und Effective-Endpunkte nur noch, dass für diese Präferenz ein Secret existiert (hasWebhookSecret: true); sie geben den Wert nie wieder zurück, und es gibt keine Möglichkeit, ihn später abzurufen. Spätere Upserts auf denselben Ereignistyp verwenden das bestehende Secret wieder, anstatt ein neues zu generieren.

8. Die Signatur verifizieren

Verwenden Sie das Signing-Secret, um zu bestätigen, dass eine Zustellung tatsächlich von Stratum stammt und nicht manipuliert oder wiederholt (Replay) wurde. Für jede signierte Anfrage:

  • Lesen Sie X-Stratum-Timestamp (Unix-Sekunden) und X-Stratum-Signature (formatiert als v1=<hex>).
  • Bilden Sie die signierte Zeichenkette, indem Sie den Timestamp und den rohen Request-Body mit einem Punkt verbinden: <timestamp>.<raw body>.
  • Berechnen Sie HMAC-SHA256 über diese Zeichenkette mit Ihrem Secret als Schlüssel und kodieren Sie das Ergebnis hexadezimal.
  • Vergleichen Sie Ihren Hex-Digest mit dem Wert nach v1= per Konstantzeit-Vergleich. Lehnen Sie die Anfrage ab, wenn er nicht übereinstimmt.
  • Lehnen Sie Anfragen ab, deren Timestamp für Ihre Toleranz zu alt ist, um sich gegen Replays zu schützen.

Berechnen Sie den HMAC über genau die Bytes, die Sie empfangen haben, vor jeder erneuten JSON-Serialisierung.

Verwandt

Siehe den API-Key-Schnellstart, den Sicherheitsüberblick, den Strategiekatalog und den APR-Rechner für mehr dazu, wie Stratum Bitfinex-Margin-Funding automatisiert.