Вебхуки-уведомления

Stratum может отправлять (POST) ваши события автоматизации фандинга на контролируемый вами HTTPS-эндпоинт. Вебхук — это канал уведомлений: вы включаете его для интересующих вас типов событий, и Stratum доставляет каждое из них в виде JSON-запроса, который вы можете направить в собственные инструменты, оповещения или дашборды. Это дополнение к уведомлениям в приложении и по электронной почте — а не замена модели безопасности вокруг вашего ограниченного по правам API-ключа Bitfinex.

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. Схема полезной нагрузки

Каждая доставка — это один JSON-объект, отправляемый с Content-Type: application/json:

  • type — имя типа события, например LOAN_EXECUTED.
  • severity — одно из INFO, WARNING или ERROR.
  • title — короткий понятный человеку заголовок.
  • body — понятное человеку сообщение.
  • createdAt — момент времени в формате ISO-8601.
  • payload — объект с полями, специфичными для типа события; может быть пустым.
  • userId — ваш числовой идентификатор пользователя.

Например (значения полей приведены лишь для иллюстрации):

  • {"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 генерирует этот секрет и возвращает его ровно один раз — в ответе на тот самый запрос обновления настроек. Сохраните его немедленно. После этого эндпоинты списка и effective лишь сообщают, что секрет для данной настройки существует (hasWebhookSecret: true); они никогда больше не возвращают само значение, и нет способа получить его позже. Последующие обновления того же типа события повторно используют существующий секрет, а не генерируют новый.

8. Проверьте подпись

Используйте секрет подписи, чтобы убедиться, что доставка действительно пришла от Stratum и не была подделана или воспроизведена повторно. Для каждого подписанного запроса:

  • Прочитайте X-Stratum-Timestamp (Unix-секунды) и X-Stratum-Signature (в формате v1=<hex>).
  • Составьте подписываемую строку, соединив временную метку и сырое тело запроса точкой: <timestamp>.<raw body>.
  • Вычислите HMAC-SHA256 по этой строке, используя ваш секрет в качестве ключа, и закодируйте результат в hex.
  • Сравните полученный hex-дайджест со значением после v1=, используя сравнение с постоянным временем. Отклоните запрос, если значения не совпадают.
  • Отклоняйте запросы, временная метка которых слишком стара для вашего допуска, чтобы защититься от повторного воспроизведения.

Вычисляйте HMAC по тем точным байтам, которые вы получили, до любой повторной сериализации JSON.

См. также

Смотрите быстрый старт по API-ключу, обзор безопасности, каталог стратегий и калькулятор APR, чтобы узнать больше о том, как Stratum автоматизирует маржинальный фандинг Bitfinex.