알림 웹훅

Stratum은 사용자가 제어하는 HTTPS 엔드포인트로 펀딩 자동화 이벤트를 POST할 수 있습니다. 웹훅은 알림 채널입니다. 관심 있는 이벤트 유형에 대해 활성화하면, Stratum이 각 이벤트를 JSON 요청으로 전달하며 사용자는 이를 자체 도구, 알림, 대시보드로 라우팅할 수 있습니다. 이는 앱 내 알림 및 이메일 알림을 보완하는 것이며, 사용자의 범위 제한 Bitfinex API 키를 둘러싼 보안 모델을 대체하지 않습니다.

1. 웹훅 채널 활성화

알림 전달은 이벤트 유형별, 채널별로 구성됩니다. 웹훅 수신을 시작하려면, 다음 본문과 함께 PUT /api/v1/settings/notifications로 환경설정 업서트를 보내세요:

  • type — 전달받을 이벤트 유형(아래 목록 참조).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — 사용자의 HTTPS 엔드포인트(최대 2048자).

현재 구성된 내용을 확인하려면, GET /api/v1/settings/notifications가 명시적으로 설정한 환경설정을 나열하고, GET /api/v1/settings/notifications/effective가 설정 화면에서 렌더링하는 기본값과 재정의가 병합된 뷰를 반환합니다. 여기에는 webhookUrl과 hasWebhookSecret 플래그가 포함됩니다.

2. 엔드포인트 요구사항

URL은 https를 사용해야 합니다. Stratum은 URL을 저장할 때와 전달 시점에 모두 검증하며, localhost나 내부/사설 네트워크 주소를 가리키는 엔드포인트는 거부합니다. 리다이렉트는 따르지 않으며, 요청은 구성한 정확한 URL로 전송됩니다. 엔드포인트는 2xx 상태로 응답해야 합니다. 그 외의 응답은 전달 실패로 처리되어 재시도됩니다.

3. 라우팅 가능한 이벤트 유형

다음 이벤트 유형을 웹훅으로 전달할 수 있습니다:

  • 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

일부 이벤트 유형은 설정에서 채널별로 토글되지 않습니다. HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE, WITHDRAWAL_DETECTED는 자동으로 관리되며 웹훅 옵트인 대상으로 노출되지 않습니다. 정기 다이제스트(DAILY_DIGEST부터 YEARLY_DIGEST까지)는 기본적으로 이메일로 전송됩니다. 웹훅으로도 전달받으려면 웹훅 채널을 명시적으로 활성화하세요.

4. 페이로드 스키마

각 전달은 Content-Type: application/json으로 전송되는 단일 JSON 객체입니다:

  • type — 이벤트 유형 이름(예: LOAN_EXECUTED).
  • severity — INFO, WARNING, ERROR 중 하나.
  • title — 사람이 읽을 수 있는 짧은 제목.
  • body — 사람이 읽을 수 있는 메시지.
  • createdAt — ISO-8601 시각.
  • payload — 유형별 필드를 담은 객체이며, 비어 있을 수 있습니다.
  • userId — 사용자의 숫자 ID.

예시(필드 값은 예시일 뿐입니다):

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

5. 헤더

모든 요청에는 다음이 포함됩니다:

  • X-Stratum-Type — 이벤트 유형 이름(본문의 type과 동일한 값).
  • User-Agent — Stratum/<version> (+https://stratum.money).

서명 시크릿이 있는 경우, 각 요청에는 X-Stratum-Timestamp와 X-Stratum-Signature도 포함됩니다(아래 서명 검증 참조).

6. 전달 및 재시도

Stratum은 엔드포인트의 응답을 최대 5초간 기다립니다. 전달이 실패하면(2xx가 아닌 응답, 타임아웃, 연결 오류) 지수 백오프로 재시도됩니다. 총 최대 6회의 전달 시도가 있으며, 연속된 시도 사이에 1분, 5분, 15분, 1시간, 4시간의 지연이 있습니다. 스케줄러가 약 60초마다 도래한 재시도를 처리합니다. 동일한 이벤트의 재전달이 무해하도록 엔드포인트를 멱등하게 설계하세요.

7. 서명 시크릿

웹훅 환경설정은 이벤트 유형별로 저장되며, 각각 고유한 서명 시크릿을 가집니다. 특정 이벤트 유형에 대해 웹훅 채널을 처음 활성화하면, Stratum이 해당 시크릿을 생성하여 단 한 번만 — 그 업서트 요청에 대한 응답에서 — 반환합니다. 즉시 저장하세요. 그 이후로 list 및 effective 엔드포인트는 해당 환경설정에 시크릿이 존재한다는 것만 보고합니다(hasWebhookSecret: true). 값 자체는 다시 반환되지 않으며, 나중에 조회할 방법이 없습니다. 동일한 이벤트 유형에 대한 이후 업서트는 새 시크릿을 생성하지 않고 기존 시크릿을 재사용합니다.

8. 서명 검증

전달이 실제로 Stratum에서 온 것이며 변조되거나 재전송되지 않았는지 확인하려면 서명 시크릿을 사용하세요. 서명된 각 요청에 대해:

  • X-Stratum-Timestamp(Unix 초)와 X-Stratum-Signature(v1=<hex> 형식)를 읽습니다.
  • 타임스탬프와 원시 요청 본문을 마침표로 연결하여 서명 대상 문자열을 만듭니다: <timestamp>.<raw body>.
  • 시크릿을 키로 사용하여 해당 문자열에 대해 HMAC-SHA256을 계산하고, 결과를 16진수로 인코딩합니다.
  • 16진수 다이제스트를 v1= 뒤의 값과 상수 시간 비교로 비교합니다. 일치하지 않으면 요청을 거부합니다.
  • 재전송 공격을 방지하기 위해 타임스탬프가 허용 범위보다 오래된 요청은 거부합니다.

HMAC은 어떠한 JSON 재직렬화 이전에 수신한 정확한 바이트에 대해 계산하세요.

관련 문서

Stratum이 Bitfinex 마진 펀딩을 자동화하는 방법에 대한 자세한 내용은 API 키 빠른 시작, 보안 개요, 전략 카탈로그, APR 계산기를 참고하세요.