Bildirim webhook'ları

Stratum, fonlama otomasyonu olaylarınızı kontrol ettiğiniz bir HTTPS uç noktasına POST edebilir. Webhook bir bildirim kanalıdır: önemsediğiniz olay türleri için onu etkinleştirirsiniz ve Stratum her birini, kendi araçlarınıza, uyarılarınıza veya panolarınıza yönlendirebileceğiniz bir JSON isteği olarak iletir. Bu, uygulama içi ve e-posta bildirimlerini tamamlar — kapsamı sınırlı Bitfinex API anahtarınız etrafındaki güvenlik modelinin yerine geçmez.

1. Webhook kanalını etkinleştirin

Bildirim teslimi her olay türü ve her kanal için ayrı ayrı yapılandırılır. Webhook almaya başlamak için PUT /api/v1/settings/notifications adresine şu gövdeyle bir tercih güncellemesi (upsert) gönderin:

  • type — teslim edilmesini istediğiniz olay türü (aşağıdaki listeye bakın).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — HTTPS uç noktanız (en fazla 2048 karakter).

Şu anda neyin yapılandırılmış olduğunu görmek için GET /api/v1/settings/notifications açık tercihlerinizi listeler ve GET /api/v1/settings/notifications/effective ayarlar ekranının üzerinden oluşturduğu, varsayılanlar ile geçersiz kılmaların birleştirilmiş görünümünü döndürür — webhookUrl değeriniz ve bir hasWebhookSecret bayrağı dahil.

2. Uç nokta gereksinimleri

URL'niz https kullanmalıdır. Stratum URL'yi hem kaydettiğinizde hem de teslim anında tekrar doğrular ve localhost'a veya iç/özel ağ adreslerine işaret eden uç noktaları reddeder. Yönlendirmeler (redirect) izlenmez — istek tam olarak yapılandırdığınız URL'ye gider. Uç noktanız bir 2xx durumuyla yanıt vermelidir; başka herhangi bir yanıt teslim hatası olarak değerlendirilir ve yeniden denenir.

3. Yönlendirebileceğiniz olay türleri

Aşağıdaki olay türleri bir webhook'a teslim edilebilir:

  • 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

Birkaç olay türü ayarlarda kanal bazında açılıp kapatılmaz — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE ve WITHDRAWAL_DETECTED sizin adınıza yönetilir ve webhook'a abone olmak için sunulmaz. Periyodik özetler (DAILY_DIGEST'ten YEARLY_DIGEST'e kadar) varsayılan olarak e-postaya gelir; bunların da webhook üzerinden gelmesini istiyorsanız webhook kanalını açıkça etkinleştirin.

4. Yük (payload) şeması

Her teslim, Content-Type: application/json ile gönderilen tek bir JSON nesnesidir:

  • type — olay türü adı, örn. LOAN_EXECUTED.
  • severity — INFO, WARNING veya ERROR değerlerinden biri.
  • title — kısa, okunabilir bir başlık.
  • body — okunabilir bir mesaj.
  • createdAt — bir ISO-8601 zaman anı.
  • payload — türe özgü alanlardan oluşan bir nesne; boş olabilir.
  • userId — sayısal kullanıcı kimliğiniz.

Örneğin (alan değerleri yalnızca açıklayıcı amaçlıdır):

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

5. Başlıklar

Her istek şunları taşır:

  • X-Stratum-Type — olay türü adı (gövdedeki type ile aynı değer).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Bir imzalama sırrınız (signing secret) olduğunda, her istek ayrıca X-Stratum-Timestamp ve X-Stratum-Signature içerir (aşağıdaki imza doğrulamasına bakın).

6. Teslim ve yeniden denemeler

Stratum, uç noktanızın yanıt vermesi için en fazla 5 saniye bekler. Bir teslim başarısız olursa — 2xx olmayan bir yanıt, bir zaman aşımı veya bir bağlantı hatası — üstel geri çekilmeyle (exponential backoff) yeniden denenir. Toplamda en fazla 6 teslim denemesi vardır; ardışık denemeler arasında 1 dakika, 5 dakika, 15 dakika, 1 saat ve 4 saatlik gecikmeler bulunur. Bir zamanlayıcı, vadesi gelen yeniden denemeleri yaklaşık her 60 saniyede bir alır. Uç noktanızı, aynı olayın yeniden teslim edilmesi zararsız olacak şekilde idempotent (etki bağışık) tasarlayın.

7. İmzalama sırrı (signing secret)

Webhook tercihleri her olay türü için ayrı saklanır ve her birinin kendi imzalama sırrı vardır. Belirli bir olay türü için webhook kanalını ilk kez etkinleştirdiğinizde, Stratum o sırrı üretir ve onu yalnızca bir kez döndürür — o upsert isteğinin yanıtında. Hemen kaydedin. Bundan sonra, liste ve etkin (effective) uç noktaları yalnızca o tercih için bir sırrın var olduğunu bildirir (hasWebhookSecret: true); değeri bir daha asla döndürmezler ve daha sonra onu almanın bir yolu yoktur. Aynı olay türüne yapılan sonraki upsert'ler yeni bir sır üretmek yerine mevcut sırrı yeniden kullanır.

8. İmzayı doğrulayın

Bir teslimin gerçekten Stratum'dan geldiğini ve değiştirilmediğini veya tekrar oynatılmadığını (replay) doğrulamak için imzalama sırrını kullanın. İmzalı her istek için:

  • X-Stratum-Timestamp (Unix saniyesi) ve X-Stratum-Signature (v1=<hex> biçiminde) değerlerini okuyun.
  • İmzalanmış dizeyi, zaman damgasını ve ham istek gövdesini bir nokta ile birleştirerek oluşturun: <timestamp>.<raw body>.
  • O dize üzerinde sırrınızı anahtar olarak kullanarak HMAC-SHA256 hesaplayın ve sonucu hex olarak kodlayın.
  • Hex özetinizi v1= sonrasındaki değerle sabit zamanlı (constant-time) bir karşılaştırmayla kıyaslayın. Eşleşmezse isteği reddedin.
  • Tekrar oynatma saldırılarına karşı koruma için, zaman damgası toleransınıza göre çok eski olan istekleri reddedin.

HMAC'i, herhangi bir JSON yeniden serileştirmesinden önce, aldığınız tam baytlar üzerinden hesaplayın.

İlgili

Stratum'un Bitfinex marj fonlamasını nasıl otomatikleştirdiği hakkında daha fazlası için API anahtarı hızlı başlangıcına, güvenlik genel bakışına, strateji kataloğuna ve APR hesaplayıcısına bakın.