Skip to main content
Subscribe to account lifecycle events via the Webhooks endpoints and react in your backend the moment something happens — no polling.

Event types

Subscribe with an explicit list or "*" for everything.
High-volume events (fill.created, account.balance_changed) are never delivered through a * subscription — an endpoint must list them explicitly. This protects existing wildcard endpoints from suddenly receiving a firehose of per-fill events. account.balance_adjusted is explicit-only as well, so existing * endpoints do not receive it.
Events carry contextual blocks where relevant: trigger (what caused it, for example rule_violation, profit_target, first_trade, firm_deactivated, firm_reactivated, claim_email, time_limit_extension, daily_loss_off_threshold), ruleType (which rule ended the account: max_loss, max_drawdown, time_limit_exceeded or inactivity on a failure, profit_target on a pass), payout (payout ID, amounts, balances), import (import key details, including claimedVia, loginAlreadyBoundToOtherCustomer, and otherBoundCustomerIds), timeLimit (extension details), dailyLossLimit (daily loss limit switch-off details), and previousAttributes for change events. On account.imported, loginAlreadyBoundToOtherCustomer and otherBoundCustomerIds appear for both import-key and claim-email triggers. loginAlreadyBoundToOtherCustomer is true, false, or null; treat null as unknown, not as false. otherBoundCustomerIds lists your own customerIds already bound to the same login, oldest first, at most 10. It is [] when the flag is false and null when unknown. Only bindings within your firm count. Imports succeed exactly as before — these fields are a signal only.

Payload format

Every delivery is a JSON object with the same envelope: For account.* events, data is the full account object as of the event: identifiers (id, accountNumber, customerId), type, status, balances (initialBalance, currentBalance, highWaterMark, dailyStartingBalance), timestamps, violationReason, metadata, plus nested context where available: trader (email, name, externalUserId), tradingPlan, tradingRule (including drawdownDenomination and drawdownTrailCeiling), and the active lockout (including cause — a stable machine-readable lockout cause such as daily_loss, max_drawdown, session_window, admin, or other; null when not recorded). The lockout block on account.lockout_created and account.lockout_updated also includes cause.

Example: account.status_changed

Example: account.failed

account.failed is sent together with the account.status_changed above and carries the same trigger and ruleType.
When your team fails an account (trigger: "admin_bulk") there is no ruleType. New values may be added, so treat an unknown ruleType as a failure all the same.

Daily loss and daily drawdown breaches

A daily loss or daily drawdown breach does not fail the account. Its open positions are closed, working orders are cancelled and the account is locked until the next trading day, when it can trade again. The account stays in_progress, so you receive no account.failed or account.status_changed, and the lock does not send account.lockout_created. To see the lock, call GET /organization/lockouts/{accountId} (or GET /organization/lockouts for every active lock). A daily-limit lock has mode trading_day, cause daily_loss or daily_drawdown, and endsAt at the daily close (4:00 PM US Central time) that ends the current trading day:
Account events sent while the lock is active show it in data.activeLockout with the same cause.

Example: account.payout_processed

Payout events add a payout block with the withdrawal details. data is the account after the payout — data.currentBalance equals payout.balance_after.
payout.mll_locked_to is set when the payout was executed with moveMllToLock; consistency_reset mirrors that request option. When a payout hits the rule’s maxPayouts, a separate account.max_payouts_reached event fires alongside it carrying the same payout.payout_id and payout.payout_count.

Example: account.payout_reversed

Payout reversal events fire when a payout is credited back to the account. The payout block shows the credited amount and the before/after balances.
The reversal restores the balance, adjusts the high-water mark and daily baseline to preserve the trailing-drawdown distance, and decrements the payout count. If the original payout had reset the consistency cycle, the cycle start is shifted accordingly.

Example: fill.created

Fill events are fill-centric: the fill is top-level and the account is nested context. account.currentBalance is the account balance recorded at the moment the fill was booked — including this fill’s realized P&L, fees, and commission — and is identical on the webhook delivery, the live event stream frame and any ?since= replay of the same event.
fill.created is one event per order once it is fully filled — filledQuantity is the order’s total and filledPrice the weighted average. Deduplicate on orderId: a repeated orderId is always a redelivery, never a second fill of the same order.

account.balance_changed

One event every time an account’s balance changes, whatever moved it. If you mirror balances on your side this is the only event you need to follow.
The values are captured at the moment the balance moved and are identical on the webhook delivery, the live WebSocket frame and the ?since= replay; the id is the same on every channel, so deduplicate on it. Like fill.created, webhook deliveries are only recorded while an endpoint explicitly lists the event; the WebSocket stream carries it regardless.
Apply account.balance_changed as it arrives and reconcile periodically against GET /v1/organization/balances — one row per account with the authoritative currentBalance, up to 500 accounts per page, and ?updatedSince= to fetch only the accounts that moved since your last check.
You can send yourself a sample of any event type with the webhook test endpoint: POST /v1/organization/webhooks/{webhookId}/test with { "eventType": "account.payout_processed", "accountId": "<account id>" } builds the payload from a real account (read-only) and delivers it to your endpoint as webhook.test.

account.claim_refused

Fires when a verified Hyperprop user whose email matches an unclaimed account’s claimEmail tries to auto-claim it and is refused because that firm customer (customerId) is already bound to a different Hyperprop login. Sent at most once per account, and delivered to wildcard (*) subscriptions alongside explicit subscribers.
An account with a claimEmail is claimed when the signed-in user is loaded, not by the sign-in call itself. The Hyperprop app loads the user every time it opens and right after the user signs in, so customers using the app need to do nothing. That is also when account.imported (or this event) fires. If you drive the flow through the API, for example in sandbox tests, call GET /platform/v1/auth/me or POST /platform/v1/user/trading-accounts/claim-pending with the user’s access token after POST /platform/v1/auth/signin. claim-pending returns the accounts it claimed, the ones it refused, and a skipped reason when it did nothing (for example email_not_verified).
When it does not fire: unverified emails, no matching account, organization team logins, accounts already claimed by someone else, or import-key redemptions. Resolution: call POST /v1/organization/trader-bindings/{bindingId}/rebind with { "email": "<claimEmail>" }. The account links the next time the customer’s login is loaded: when they next open the Hyperprop app, or on GET /platform/v1/auth/me or POST /platform/v1/user/trading-accounts/claim-pending.

account.daily_loss_limit_off and account.daily_loss_limit_on

Sent for rules that set dailyLossOffThreshold (daily loss limit switch-off), once per change, at the daily close. account.daily_loss_limit_off means the daily loss limit is off from the next trading day; account.daily_loss_limit_on means it applies again from the next trading day.

account.trading_day_reverted and account.trading_day_revert_undone

Sent when Time Machine reverts trading days on an account, or when a revert is undone and the days are restored. One event per account affected by the batch.
For account.trading_day_revert_undone, the payload is similar but the block is named revertUndo with restoredFillIds and restoredFillsTruncated instead, and the account shows its state after the undo. Use /revert-batches/{batchId} to see full batch details.
To reconcile reverted days, call /reconciliation, /snapshots/accounts, or /snapshots/fills with ?includeReverted=true. Voided fills return flagged (voided, voidedAt, revertBatchId) and affected snapshots carry a reverted block. The default (false) omits them, matching prior behavior.

Verifying signatures

Every delivery is HMAC-SHA256 signed with your endpoint’s secret (whsec_..., shown when you create the webhook). Request headers: The signed message is `${timestamp}.${rawBody}`:
Compute the HMAC over the raw request body, before any JSON parsing — re-serialized JSON may not match byte-for-byte.

Delivery, retries, and auto-disable

  • Your endpoint should respond 2xx within 10 seconds; anything else counts as a failed attempt.
  • Failed deliveries retry up to 5 attempts with backoff: immediately, then after 1 min, 5 min, 30 min, and 2 h.
  • Consecutive failures eventually auto-disable the endpoint (you can re-enable it from the dashboard or API once your endpoint is healthy).
  • Any event can be redelivered on demand from the dashboard or API — which is also why you should deduplicate.

Deduplication

Store X-Hyperprop-Delivery IDs you’ve processed and skip repeats. Retries and manual redeliveries reuse the same event payload, so an idempotent consumer is all you need for exactly-once effects.