Notificatiewebhooks

Stratum kan je funding-automatiseringsgebeurtenissen POST'en naar een HTTPS-endpoint dat je zelf beheert. De webhook is een notificatiekanaal: je schakelt het in voor de gebeurtenistypen waar je om geeft, en Stratum levert elk daarvan af als een JSON-verzoek dat je kunt routeren naar je eigen tooling, alerts of dashboards. Dit is een aanvulling op de notificaties in de app en per e-mail — geen vervanging van het beveiligingsmodel rond je scoped Bitfinex API-sleutel.

1. Schakel het webhook-kanaal in

Notificatielevering wordt geconfigureerd per gebeurtenistype en per kanaal. Om webhooks te gaan ontvangen, stuur je een voorkeuren-upsert naar PUT /api/v1/settings/notifications met de body:

  • type — het gebeurtenistype dat je geleverd wilt hebben (zie de lijst hieronder).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — je HTTPS-endpoint (maximaal 2048 tekens).

Om te zien wat je momenteel hebt geconfigureerd, toont GET /api/v1/settings/notifications je expliciete voorkeuren, en GET /api/v1/settings/notifications/effective geeft de samengevoegde weergave van standaardwaarden plus overrides terug waarop het instellingenscherm is gebaseerd — inclusief je webhookUrl en een hasWebhookSecret-vlag.

2. Vereisten voor het endpoint

Je URL moet https gebruiken. Stratum valideert de URL zowel wanneer je deze opslaat als opnieuw op het moment van levering, en weigert endpoints die wijzen naar localhost of interne/private netwerkadressen. Redirects worden niet gevolgd — het verzoek gaat naar de exacte URL die je hebt geconfigureerd. Je endpoint moet reageren met een 2xx-status; elke andere response wordt behandeld als een mislukte levering en opnieuw geprobeerd.

3. Gebeurtenistypen die je kunt routeren

De volgende gebeurtenistypen kunnen aan een webhook worden geleverd:

  • 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

Een paar gebeurtenistypen worden niet per kanaal in de instellingen geschakeld — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE en WITHDRAWAL_DETECTED worden voor je beheerd en zijn niet beschikbaar om voor een webhook in te schakelen. De periodieke digests (DAILY_DIGEST tot en met YEARLY_DIGEST) gaan standaard naar e-mail; schakel het webhook-kanaal expliciet in als je ze daar ook geleverd wilt hebben.

4. Payload-schema

Elke levering is één JSON-object dat wordt verzonden met Content-Type: application/json:

  • type — de naam van het gebeurtenistype, bijv. LOAN_EXECUTED.
  • severity — een van INFO, WARNING of ERROR.
  • title — een korte, voor mensen leesbare titel.
  • body — een voor mensen leesbaar bericht.
  • createdAt — een ISO-8601-tijdstip.
  • payload — een object met typespecifieke velden; dit kan leeg zijn.
  • userId — je numerieke gebruikers-id.

Bijvoorbeeld (veldwaarden zijn slechts ter illustratie):

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

5. Headers

Elk verzoek bevat:

  • X-Stratum-Type — de naam van het gebeurtenistype (dezelfde waarde als type in de body).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Wanneer je een ondertekeningsgeheim hebt, bevat elk verzoek ook X-Stratum-Timestamp en X-Stratum-Signature (zie handtekeningverificatie hieronder).

6. Levering en herhaalpogingen

Stratum wacht maximaal 5 seconden tot je endpoint reageert. Als een levering mislukt — een non-2xx-response, een timeout of een verbindingsfout — wordt deze opnieuw geprobeerd met exponentiële backoff. Er zijn in totaal maximaal 6 leveringspogingen, met vertragingen van 1 minuut, 5 minuten, 15 minuten, 1 uur en 4 uur tussen de opeenvolgende pogingen. Een scheduler pakt verschuldigde herhaalpogingen ongeveer elke 60 seconden op. Ontwerp je endpoint zo dat het idempotent is, zodat een herhaalde levering van dezelfde gebeurtenis geen kwaad kan.

7. Ondertekeningsgeheim

Webhook-voorkeuren worden per gebeurtenistype opgeslagen, en elk daarvan heeft een eigen ondertekeningsgeheim. De eerste keer dat je het webhook-kanaal inschakelt voor een bepaald gebeurtenistype, genereert Stratum dat geheim en geeft het precies één keer terug — in de response op die upsert-aanvraag. Sla het direct op. Daarna melden de list- en effective-endpoints alleen dat er een geheim bestaat voor die voorkeur (hasWebhookSecret: true); ze geven de waarde nooit meer terug, en er is geen manier om deze later op te halen. Latere upserts voor hetzelfde gebeurtenistype hergebruiken het bestaande geheim in plaats van een nieuw te genereren.

8. Verifieer de handtekening

Gebruik het ondertekeningsgeheim om te bevestigen dat een levering daadwerkelijk van Stratum afkomstig is en niet is gemanipuleerd of opnieuw afgespeeld. Voor elk ondertekend verzoek:

  • Lees X-Stratum-Timestamp (Unix-seconden) en X-Stratum-Signature (geformatteerd als v1=<hex>).
  • Bouw de te ondertekenen string door de timestamp en de ruwe request-body samen te voegen met een punt: <timestamp>.<raw body>.
  • Bereken HMAC-SHA256 over die string met je geheim als sleutel, en codeer het resultaat als hex.
  • Vergelijk je hex-digest met de waarde na v1= met behulp van een constant-time-vergelijking. Weiger het verzoek als het niet overeenkomt.
  • Weiger verzoeken waarvan de timestamp ouder is dan jouw tolerantie, om replays te voorkomen.

Bereken de HMAC over de exacte bytes die je hebt ontvangen, vóór enige JSON-herserialisatie.

Gerelateerd

Zie de API-sleutel-quickstart, het beveiligingsoverzicht, de strategiecatalogus en de APR-calculator voor meer over hoe Stratum margin funding op Bitfinex automatiseert.