Webhooks de notificación

Stratum puede enviar mediante POST tus eventos de automatización de funding a un endpoint HTTPS que tú controlas. El webhook es un canal de notificación: lo habilitas para los tipos de evento que te interesan y Stratum entrega cada uno como una petición JSON que puedes encaminar hacia tus propias herramientas, alertas o paneles. Es un complemento de las notificaciones dentro de la app y por correo electrónico, no un reemplazo del modelo de seguridad que rodea tu clave API de Bitfinex con permisos acotados.

1. Habilita el canal de webhook

La entrega de notificaciones se configura por tipo de evento y por canal. Para empezar a recibir webhooks, envía un upsert de preferencia a PUT /api/v1/settings/notifications con el cuerpo:

  • type — el tipo de evento que quieres recibir (consulta la lista de abajo).
  • channel — WEBHOOK.
  • enabled — true.
  • webhookUrl — tu endpoint HTTPS (máximo 2048 caracteres).

Para ver lo que tienes configurado actualmente, GET /api/v1/settings/notifications lista tus preferencias explícitas, y GET /api/v1/settings/notifications/effective devuelve la vista combinada de valores por defecto más anulaciones desde la que se renderiza la pantalla de ajustes, incluyendo tu webhookUrl y un indicador hasWebhookSecret.

2. Requisitos del endpoint

Tu URL debe usar https. Stratum valida la URL tanto cuando la guardas como de nuevo en el momento de la entrega, y rechaza endpoints que apunten a localhost o a direcciones de red internas/privadas. No se siguen redirecciones: la petición va a la URL exacta que configuraste. Tu endpoint debería responder con un estado 2xx; cualquier otra respuesta se trata como un fallo de entrega y se reintenta.

3. Tipos de evento que puedes encaminar

Los siguientes tipos de evento se pueden entregar a un 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

Algunos tipos de evento no se activan por canal en los ajustes: HIGH_UTILIZATION, OFFER_FILLED, EARNINGS_MILESTONE y WITHDRAWAL_DETECTED se gestionan automáticamente por ti y no están expuestos para suscripción por webhook. Los resúmenes periódicos (DAILY_DIGEST hasta YEARLY_DIGEST) se entregan por correo electrónico de forma predeterminada; habilita el canal de webhook explícitamente si también quieres recibirlos allí.

4. Esquema de payload

Cada entrega es un único objeto JSON enviado con Content-Type: application/json:

  • type — el nombre del tipo de evento, p. ej. LOAN_EXECUTED.
  • severity — uno de INFO, WARNING o ERROR.
  • title — un título corto legible por humanos.
  • body — un mensaje legible por humanos.
  • createdAt — un instante ISO-8601.
  • payload — un objeto con campos específicos del tipo; puede estar vacío.
  • userId — tu id de usuario numérico.

Por ejemplo (los valores de los campos son solo 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. Cabeceras

Cada petición lleva:

  • X-Stratum-Type — el nombre del tipo de evento (el mismo valor que el type del cuerpo).
  • User-Agent — Stratum/<version> (+https://stratum.money).

Cuando tienes un secreto de firma, cada petición incluye además X-Stratum-Timestamp y X-Stratum-Signature (consulta la verificación de firmas más abajo).

6. Entrega y reintentos

Stratum espera hasta 5 segundos a que tu endpoint responda. Si una entrega falla —una respuesta distinta de 2xx, un timeout o un error de conexión— se reintenta con backoff exponencial. Hay hasta 6 intentos de entrega en total, con retrasos de 1 minuto, 5 minutos, 15 minutos, 1 hora y 4 horas entre intentos sucesivos. Un planificador recoge los reintentos pendientes aproximadamente cada 60 segundos. Diseña tu endpoint para que sea idempotente, de modo que una entrega reintentada del mismo evento sea inofensiva.

7. Secreto de firma

Las preferencias de webhook se almacenan por tipo de evento, y cada una lleva su propio secreto de firma. La primera vez que habilitas el canal de webhook para un tipo de evento dado, Stratum genera ese secreto y lo devuelve una sola vez, en la respuesta a esa petición de upsert. Guárdalo de inmediato. Después de eso, los endpoints de listado y de vista efectiva solo informan de que existe un secreto para esa preferencia (hasWebhookSecret: true); nunca vuelven a devolver el valor, y no hay forma de recuperarlo más tarde. Los upserts posteriores al mismo tipo de evento reutilizan el secreto existente en lugar de generar uno nuevo.

8. Verifica la firma

Usa el secreto de firma para confirmar que una entrega realmente provino de Stratum y no fue manipulada ni reenviada. Para cada petición firmada:

  • Lee X-Stratum-Timestamp (segundos Unix) y X-Stratum-Signature (con formato v1=<hex>).
  • Construye la cadena firmada uniendo el timestamp y el cuerpo crudo de la petición con un punto: <timestamp>.<raw body>.
  • Calcula HMAC-SHA256 sobre esa cadena usando tu secreto como clave, y codifica el resultado en hexadecimal.
  • Compara tu digest hexadecimal con el valor que sigue a v1= usando una comparación de tiempo constante. Rechaza la petición si no coincide.
  • Rechaza las peticiones cuyo timestamp sea demasiado antiguo según tu tolerancia, para protegerte de reenvíos.

Calcula el HMAC sobre los bytes exactos que recibiste, antes de cualquier reserialización del JSON.

Relacionado

Consulta el inicio rápido de la clave API, el resumen de seguridad, el catálogo de estrategias y la calculadora de APR para saber más sobre cómo Stratum automatiza el margin funding de Bitfinex.