Event types
Subscribe with an explicit list or
"*" for everything.
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 staysin_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:
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.
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.
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.
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
StoreX-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.