Webhooks

Live account metrics

Subscribe to authoritative account valuations over a metered WebSocket connection.

Use the live-metrics WebSocket while an account needs continuous monitoring. Each valuation contains balance, equity, margin, freeMargin, marginLevel, and openPositionCount.

Every authoritative valuation change is published with a consecutive account sequence and measurement time. Each sample also includes the lowest equity observed while the server coalesced that update interval, with its measurement time. Koneth retains a short replay window so a reconnecting consumer can request samples after its last durably processed sequence.

Connect

Open wss://YOUR-KONETH-MAIN/api/v1/management/live-metrics with a Management API key that has metrics:read. This connection is intended for an organization’s backend because browser WebSocket APIs cannot attach the required Authorization header.

import WebSocket from "ws";

const socket = new WebSocket(
  "wss://YOUR-KONETH-MAIN/api/v1/management/live-metrics",
  { headers: { Authorization: `Management ${process.env.KONETH_API_KEY}` } },
);

The first message identifies the connection session:

{"type":"connected","sessionId":"e5587cc7-a438-4023-a5ca-679f90300dd3"}

{"type":"subscribe","serverId":"srv_123","accountNumber":"100042","afterSequence":8142}

Omit afterSequence for the latest stored sample. Supply the last sequence your application durably processed after reconnecting.

Before replayed samples, Koneth sends a replay message with firstAvailableSequence and replayTruncated. Reconcile through the account and positions endpoints when replayTruncated is true.

{
  "type": "account.metrics",
  "eventId": "1d4fc5f3-4d93-4db1-87da-5a2098ed84e0",
  "serverId": "srv_123",
  "accountNumber": "100042",
  "sequence": 8143,
  "measuredAt": "2026-08-30T14:25:40.221Z",
  "balance": 100000,
  "equity": 97480.5,
  "margin": 2000,
  "freeMargin": 95480.5,
  "marginLevel": 4874.025,
  "openPositionCount": 2,
  "intervalMinimumEquity": 97480.5,
  "intervalMinimumMeasuredAt": "2026-08-30T14:25:40.221Z"
}

Persist the sequence only after your rules have durably processed the sample. If a sequence gap exceeds the replay window, fetch the current account state and open positions before resuming enforcement.

Unsubscribe safely

{"type":"unsubscribe","serverId":"srv_123","accountNumber":"100042"}

A position.closed webhook may represent one of several positions. Before unsubscribing, call GET /api/v1/management/servers/{serverId}/accounts/{accountNumber}/positions?status=open&limit=1. Unsubscribe only when pagination.total is 0 and no other rule requires monitoring.

Send the text frame ping to receive pong. Reconnect with backoff, then resume from the last processed sequence.

Connect

Subscribe and replay

Unsubscribe safely