Webhooks de notificação

O Stratum pode fazer POST dos seus eventos de automação de funding para um endpoint HTTPS que você controla. O webhook é um canal de notificação: você o habilita para os tipos de evento que lhe interessam, e o Stratum entrega cada um como uma requisição JSON que você pode encaminhar para suas próprias ferramentas, alertas ou dashboards. Isso é um complemento às notificações no app e por e-mail — não um substituto do modelo de segurança em torno da sua chave de API da Bitfinex com escopo.

1. Habilite o canal de webhook

A entrega de notificações é configurada por tipo de evento e por canal. Para começar a receber webhooks, envie um upsert de preferência para PUT /api/v1/settings/notifications com o corpo:

  • type — o tipo de evento que você quer receber (veja a lista abaixo).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — seu endpoint HTTPS (máximo de 2048 caracteres).

Para ver o que você tem configurado no momento, GET /api/v1/settings/notifications lista suas preferências explícitas, e GET /api/v1/settings/notifications/effective retorna a visão mesclada de padrões mais sobrescrições a partir da qual a tela de configurações é renderizada — incluindo sua webhookUrl e uma flag hasWebhookSecret.

2. Requisitos do endpoint

Sua URL precisa usar https. O Stratum valida a URL tanto ao salvá-la quanto novamente no momento da entrega, e rejeita endpoints que apontam para localhost ou endereços de rede interna/privada. Redirecionamentos não são seguidos — a requisição vai para a URL exata que você configurou. Seu endpoint deve responder com um status 2xx; qualquer outra resposta é tratada como uma falha de entrega e é retentada.

3. Tipos de evento que você pode encaminhar

Os seguintes tipos de evento podem ser entregues a um 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

Alguns tipos de evento não são ativados por canal nas configurações — HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE e WITHDRAWAL_DETECTED são gerenciados por você e não estão expostos para opt-in via webhook. Os resumos periódicos (DAILY_DIGEST até YEARLY_DIGEST) têm o e-mail como padrão; habilite o canal de webhook explicitamente se quiser recebê-los lá também.

4. Esquema de payload

Cada entrega é um único objeto JSON enviado com Content-Type: application/json:

  • type — o nome do tipo de evento, p. ex. LOAN_EXECUTED.
  • severity — um de INFO, WARNING ou ERROR.
  • title — um título curto legível por humanos.
  • body — uma mensagem legível por humanos.
  • createdAt — um instante em ISO-8601.
  • payload — um objeto com campos específicos do tipo; pode estar vazio.
  • userId — seu id numérico de usuário.

Por exemplo (os valores dos campos são apenas ilustrativos):

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

5. Cabeçalhos

Toda requisição carrega:

  • X-Stratum-Type — o nome do tipo de evento (o mesmo valor do type do corpo).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Quando você tem um segredo de assinatura, cada requisição também inclui X-Stratum-Timestamp e X-Stratum-Signature (veja a verificação de assinatura abaixo).

6. Entrega e retentativas

O Stratum aguarda até 5 segundos pela resposta do seu endpoint. Se uma entrega falhar — uma resposta não-2xx, um timeout ou um erro de conexão — ela é retentada com backoff exponencial. São até 6 tentativas de entrega no total, com atrasos de 1 minuto, 5 minutos, 15 minutos, 1 hora e 4 horas entre as tentativas sucessivas. Um agendador recolhe as retentativas devidas a cada cerca de 60 segundos. Projete seu endpoint para ser idempotente, de modo que uma entrega retentada do mesmo evento seja inofensiva.

7. Segredo de assinatura

As preferências de webhook são armazenadas por tipo de evento, e cada uma carrega seu próprio segredo de assinatura. Na primeira vez que você habilita o canal de webhook para um determinado tipo de evento, o Stratum gera esse segredo e o retorna exatamente uma vez — na resposta àquela requisição de upsert. Salve-o imediatamente. Depois disso, os endpoints de listagem e effective apenas informam que existe um segredo para essa preferência (hasWebhookSecret: true); eles nunca retornam o valor novamente, e não há forma de recuperá-lo depois. Upserts posteriores ao mesmo tipo de evento reutilizam o segredo existente em vez de gerar um novo.

8. Verifique a assinatura

Use o segredo de assinatura para confirmar que uma entrega veio genuinamente do Stratum e não foi adulterada ou reproduzida. Para cada requisição assinada:

  • Leia X-Stratum-Timestamp (segundos Unix) e X-Stratum-Signature (formatado como v1=<hex>).
  • Monte a string assinada juntando o timestamp e o corpo bruto da requisição com um ponto: <timestamp>.<raw body>.
  • Calcule HMAC-SHA256 sobre essa string usando seu segredo como chave, e codifique o resultado em hexadecimal.
  • Compare seu digest hexadecimal com o valor após v1= usando uma comparação de tempo constante. Rejeite a requisição se não corresponder.
  • Rejeite requisições cujo timestamp seja velho demais para a sua tolerância, para se proteger contra replays.

Calcule o HMAC sobre os bytes exatos que você recebeu, antes de qualquer reserialização do JSON.

Relacionados

Veja o início rápido da chave de API, a visão geral de segurança, o catálogo de estratégias e a calculadora de APR para saber mais sobre como o Stratum automatiza o margin funding na Bitfinex.