Webhook thông báo

Stratum có thể POST các sự kiện tự động hóa cấp vốn của bạn đến một endpoint HTTPS mà bạn kiểm soát. Webhook là một kênh thông báo: bạn bật nó cho các loại sự kiện bạn quan tâm, và Stratum gửi từng sự kiện dưới dạng một yêu cầu JSON mà bạn có thể định tuyến vào công cụ, cảnh báo hoặc bảng điều khiển của riêng mình. Đây là phần bổ sung cho các thông báo trong ứng dụng và qua email — không phải là sự thay thế cho mô hình bảo mật xoay quanh khóa API Bitfinex có phạm vi giới hạn của bạn.

1. Bật kênh webhook

Việc gửi thông báo được cấu hình theo từng loại sự kiện và từng kênh. Để bắt đầu nhận webhook, hãy gửi một preference upsert đến PUT /api/v1/settings/notifications với nội dung:

  • type — loại sự kiện bạn muốn được gửi (xem danh sách bên dưới).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — endpoint HTTPS của bạn (tối đa 2048 ký tự).

Để xem những gì bạn hiện đang cấu hình, GET /api/v1/settings/notifications liệt kê các preference rõ ràng của bạn, và GET /api/v1/settings/notifications/effective trả về chế độ xem hợp nhất giữa giá trị mặc định và các tùy chỉnh mà màn hình cài đặt dựa vào để hiển thị — bao gồm webhookUrl của bạn và một cờ hasWebhookSecret.

2. Yêu cầu đối với endpoint

URL của bạn phải dùng https. Stratum xác thực URL cả khi bạn lưu nó và một lần nữa tại thời điểm gửi, đồng thời từ chối các endpoint trỏ đến localhost hoặc các địa chỉ mạng nội bộ/riêng tư. Các chuyển hướng (redirect) không được theo dõi — yêu cầu được gửi đến đúng URL bạn đã cấu hình. Endpoint của bạn nên phản hồi với mã trạng thái 2xx; bất kỳ phản hồi nào khác đều được coi là gửi thất bại và sẽ được gửi lại.

3. Các loại sự kiện bạn có thể định tuyến

Các loại sự kiện sau có thể được gửi đến một 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

Một vài loại sự kiện không được bật/tắt theo từng kênh trong phần cài đặt — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE và WITHDRAWAL_DETECTED được quản lý sẵn cho bạn và không được mở để đăng ký qua webhook. Các bản tổng hợp định kỳ (DAILY_DIGEST đến YEARLY_DIGEST) mặc định gửi qua email; hãy bật kênh webhook một cách rõ ràng nếu bạn cũng muốn nhận chúng ở đó.

4. Lược đồ payload

Mỗi lần gửi là một đối tượng JSON duy nhất được gửi với Content-Type: application/json:

  • type — tên loại sự kiện, ví dụ LOAN_EXECUTED.
  • severity — một trong các giá trị INFO, WARNING hoặc ERROR.
  • title — một tiêu đề ngắn, dễ đọc cho con người.
  • body — một thông điệp dễ đọc cho con người.
  • createdAt — một thời điểm theo định dạng ISO-8601.
  • payload — một đối tượng chứa các trường đặc thù theo loại; nó có thể rỗng.
  • userId — id người dùng dạng số của bạn.

Ví dụ (các giá trị trường chỉ mang tính minh họa):

  • {"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

Mỗi yêu cầu mang theo:

  • X-Stratum-Type — tên loại sự kiện (cùng giá trị với type trong nội dung).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Khi bạn có một secret ký, mỗi yêu cầu cũng bao gồm X-Stratum-Timestamp và X-Stratum-Signature (xem phần xác minh chữ ký bên dưới).

6. Gửi và gửi lại

Stratum chờ tối đa 5 giây để endpoint của bạn phản hồi. Nếu một lần gửi thất bại — phản hồi không phải 2xx, hết thời gian chờ, hoặc lỗi kết nối — nó sẽ được gửi lại với cơ chế backoff theo cấp số nhân. Có tối đa 6 lần gửi tổng cộng, với các khoảng trễ là 1 phút, 5 phút, 15 phút, 1 giờ và 4 giờ giữa các lần thử liên tiếp. Một scheduler sẽ tiếp nhận các lần gửi lại đến hạn khoảng mỗi 60 giây. Hãy thiết kế endpoint của bạn để có tính idempotent, để việc gửi lại cùng một sự kiện không gây hại.

7. Secret ký

Các preference webhook được lưu theo từng loại sự kiện, và mỗi cái mang theo secret ký của riêng nó. Lần đầu tiên bạn bật kênh webhook cho một loại sự kiện nhất định, Stratum tạo secret đó và trả về nó đúng một lần — trong phản hồi của yêu cầu upsert đó. Hãy lưu nó ngay lập tức. Sau đó, các endpoint list và effective chỉ báo rằng một secret tồn tại cho preference đó (hasWebhookSecret: true); chúng không bao giờ trả về giá trị một lần nữa, và không có cách nào để lấy lại nó sau này. Các lần upsert sau cho cùng một loại sự kiện sẽ tái sử dụng secret hiện có thay vì tạo một secret mới.

8. Xác minh chữ ký

Sử dụng secret ký để xác nhận một lần gửi thực sự đến từ Stratum và không bị giả mạo hay phát lại. Với mỗi yêu cầu đã ký:

  • Đọc X-Stratum-Timestamp (giây Unix) và X-Stratum-Signature (định dạng v1=<hex>).
  • Xây dựng chuỗi đã ký bằng cách nối timestamp và nội dung yêu cầu thô bằng một dấu chấm: <timestamp>.<raw body>.
  • Tính HMAC-SHA256 trên chuỗi đó bằng secret của bạn làm khóa, rồi mã hóa kết quả thành hex.
  • So sánh hex digest của bạn với giá trị sau v1= bằng phép so sánh thời gian hằng số (constant-time). Từ chối yêu cầu nếu nó không khớp.
  • Từ chối các yêu cầu có timestamp quá cũ so với ngưỡng dung sai của bạn để phòng chống phát lại.

Hãy tính HMAC trên đúng các byte bạn đã nhận, trước bất kỳ thao tác tái-tuần-tự-hóa JSON nào.

Liên quan

Xem hướng dẫn nhanh về khóa API, tổng quan bảo mật, danh mục chiến lược và máy tính APR để tìm hiểu thêm về cách Stratum tự động hóa cấp vốn ký quỹ Bitfinex.