Register a webhook endpoint
Register a URL to receive real-time event notifications via HTTP POST.
How it works:
- You provide an HTTPS URL and choose which events to subscribe to
- Hyperprop returns a signing secret (shown once — save it)
- When events occur, we POST a JSON payload to your URL with an HMAC-SHA256 signature
- Verify the signature using the secret to ensure the payload is authentic
Available events:
| Event | Description |
|---|---|
account.created | A new trading account was provisioned |
account.status_changed | Account status changed (not_started → in_progress → passed/failed/expired). Turning an account off or back on (POST /trading-accounts//deactivate · /reactivate) moves it to or from inactive with trigger firm_deactivated / firm_reactivated and your reason at the top level of the payload |
account.updated | Account fields updated (balance, metadata, HWM) |
account.imported | A trader redeemed an import key inside the Hyperprop app — the account now has its owner. Payload carries an import block: { importKey, importedUserId, importedEmail, importedAt, loginAlreadyBoundToOtherCustomer, otherBoundCustomerIds } so you can verify who redeemed which key and when, and spot a login shared between your customers (see below). Billing + market data start at this moment. Store import.importedEmail on your customer’s profile — that login is now soulbound to the account’s customerId and all the customer’s future imports must use it (see GET /trader-bindings). |
account.unlinked | You unlinked a not-yet-started account via POST /trading-accounts//unlink. Payload carries an import block: { voidedImportKey, newImportKey, unlinkedUserId, unlinkedEmail } — the fresh key is ready to hand out. Note: the customer’s soulbound binding survives unlink — if the customer needs a new Hyperprop login, rebind them via POST /trader-bindings//rebind. |
account.passed | Account passed — profit target reached or admin update (convenience — also fires account.status_changed) |
account.failed | Account failed — live rule violation (max loss, max drawdown, account time limit, inactivity) or admin update (convenience — also fires account.status_changed). A daily loss or daily drawdown breach does not fail the account (see Rule violation alerts below) |
account.lockout_created | Trading lockout applied to an account: one your team created, or the plan’s daily profit target or best-day stop locking it for the day |
account.lockout_removed | Trading lockout removed from an account |
account.lockout_updated | Lockout details changed (reason, end time) |
account.payout_processed | A payout (balance withdrawal) was executed on an account |
account.max_payouts_reached | The account reached its rule’s maxPayouts with this payout — your “move trader to live” trigger |
account.payout_reversed | A payout was reversed via POST /accounts//payouts//reverse — the withdrawn amount was credited back to the balance |
account.time_limit_extended | The account reached the end of its time limit (maxAccountDays) with total profit above the rule’s timeLimitExtensionMinProgressPct, so it got its one-time timeLimitExtensionDays extension instead of failing. Payload carries a timeLimit block (see below). Fires at most once per account |
account.daily_loss_limit_off | At a daily close the account’s end-of-day balance was at or above its starting balance plus the rule’s dailyLossOffThreshold, so its daily loss limit is not enforced from the next trading day. Payload carries a dailyLossLimit block (see below). Only for rule sets that set dailyLossOffThreshold |
account.daily_loss_limit_on | The daily loss limit applies again from the next trading day: a while_above rule’s end-of-day balance fell below the target, or the rule no longer sets dailyLossOffThreshold. Payload carries a dailyLossLimit block |
account.claim_refused | A Hyperprop user whose verified email equals the account’s claimEmail tried to claim it automatically and was refused, so the account is still unassigned. Reasons: TRADER_ALREADY_BOUND (the account’s customerId is bound to a different Hyperprop login) and TRADER_DECLINED (the owner of the claim email declined the link in the app). Payload carries a claimRefusal block (see below). Fires at most once per account, refusal code and login |
purchase.created | A new purchase was recorded for the organization |
purchase.status_changed | Purchase status changed (pending → paid, paid → refunded/cancelled) |
trader.created | A new trader was associated with the organization |
snapshot.ready | End-of-day snapshots for a trading day are computed and queryable — fire your EOD import off this instead of guessing a time |
fill.created | An order executed quantity — fires once when the order reaches a terminal state: fully filled, or cancelled/rejected/expired after a partial execution. Near-real-time intraday fill stream (explicit subscription only, see below) |
| account.balance_changed | The account’s balance moved. One event per change with previousBalance, currentBalance, change, reason (fill · payout · revert · adjustment), orderId / payoutId where applicable and occurredAt. Same id and values on the WebSocket frame and the ?since= replay, so you can dedupe across channels on id. Explicit subscription only (see below) |
| account.balance_adjusted | You credited or debited the account with POST /trading-accounts//balance-adjustments. Payload carries a balanceAdjustment block (see below). One event per adjustment, never for a replay of the same reference. Explicit subscription only (see below) |
| account.trading_day_reverted | A Time Machine revert restored the account to an earlier point (single or bulk, end-of-day or point-in-time). One event per account per batch, sent as the account is reverted. Payload carries a revert block (see below) with the batch, restore point, affected trading days, the day snapshots it changed and the voided fills |
| account.trading_day_revert_undone | A revert batch was undone for the account: its voided fills count again and its day snapshots are back. Same revert.batchId as the revert event |
| risk.report_ready | The daily risk reports for a trading day are stored and readable at data.reportUrl (GET /risk/reports/). Once per organization and trading day, after the session closes. Explicit subscription only |
| risk.hedge_pair_flagged | Two different traders held opposite positions on the same market at the same time. One event per pair of positions, same row as in the daily report. Explicit subscription only |
| risk.copy_trading_flagged | Three or more traders opened the same position within seconds, or two traders did so on two or more days. One event per group or pair. Explicit subscription only |
| risk.shared_device_flagged | A device, or an address with overlapping sessions or trading, was used by more than one of your traders on the day. Explicit subscription only |
| trader.signed_in | One of your traders signed in to the trading platform: time, address, country, app and version and device id when the app sends them, and every account of the trader with your customerId. Explicit subscription only |
| alert.limit_crossed | A figure reached the alert limit you set with PUT /risk/alert-limits: open profit owed, accounts near breach, or markets over their exposure limit. Checked every 5 minutes; once per crossing. Explicit subscription only |
| alert.limit_cleared | The figure fell back more than 5% below that limit. Explicit subscription only |
Use ["*"] to subscribe to all events (including future event types).
Exception: fill.created, account.balance_changed, account.balance_adjusted, the risk.* events, trader.signed_in and the alert.* events are never delivered through a ["*"] wildcard — an endpoint must list them explicitly in its events array. The first two are high-volume; the others are opt-in so existing endpoints do not receive a new event type.
account.balance_changed is the one event to follow if you keep your own copy of balances: every fill, payout, adjustment and trading-day revert produces exactly one. Payload:
{
"id": "evt_9f1c...",
"type": "account.balance_changed",
"createdAt": "2026-09-09T20:14:08.412Z",
"organizationId": "a6fcc0ce-...",
"data": {
"previousBalance": 25434.67,
"currentBalance": 25806.63,
"change": 371.96,
"reason": "fill",
"orderId": "44444444-4444-4444-8444-444444444444",
"payoutId": null,
"occurredAt": "2026-09-09T20:14:08.107Z",
"account": { "id": "ddf46c59-...", "accountNumber": "ACMEEV...", "customerId": "1e38d177-...", "status": "in_progress", "currentBalance": 25806.63 },
"trader": { "email": "trader@example.com", "name": "…", "externalUserId": null, "metadata": {} }
},
"previousAttributes": { "currentBalance": 25434.67 }
}
Like fills, balance webhooks are only recorded while an active endpoint lists account.balance_changed; the WebSocket stream delivers and replays them regardless. Reconcile against GET /platform/v1/organization/balances on your own schedule.
Fill webhooks are not recorded until you subscribe. Because a wildcard
cannot opt you into fills, fill webhook deliveries are only written for
organizations that have an active endpoint explicitly listing fill.created.
Adding it starts webhook delivery within seconds, but fills that occurred
before you subscribed are not re-delivered — webhooks are
forward-looking. This gate applies to the webhook channel only: the WebSocket
event stream delivers and replays fills regardless of webhook configuration.
For history, read fills from
GET /platform/v1/organization/reconciliation for any past day.
account.trading_day_reverted: sent for each account a Time Machine revert changed, right after that account is reverted (a background bulk revert sends them as it works through its accounts). It tells you which trades no longer count and which days changed, so you can correct your own records. The account object in data is the account after the revert; previousAttributes holds the values the revert changed. The revert block:
| Field | Meaning |
|---|---|
batchId | The revert batch (GET /revert-batches/{batchId}; undo with POST /revert-batches/{batchId}/undo) |
scope | single or bulk |
mode | end_of_day (restored to the close of restoredTo) or point_in_time (restored to the instant revertToUtc) |
requestedDay, restoredTo, revertToUtc, cutoffUtc | The day asked for, the point actually restored (a trading day, an ISO instant, or initial_state), and the instant after which activity was voided |
reason | The reason given for the revert |
initiatedBy | firm_user, api_key or hyperprop (no personal data) |
revertedAt | When the revert ran |
affectedTradingDays | Every trading day with a voided fill or a changed snapshot |
balanceBefore, balanceAfter, statusBefore, statusAfter | The account before and after |
snapshots | Changed day snapshots: tradingDay, action (voided: the day no longer counts; cut_at_restore_point: the day keeps its activity up to the restore point), before and after values (after is null for a voided day) |
voidedFillCount, voidedFills, voidedFillsTruncated | The fills that no longer count, oldest first. id is the fill id the fills and reconciliation endpoints return. At most 500 inline; when truncated, read all of them from GET /revert-batches/{batchId}/accounts/{accountId}/voided-fills |
To re-read a day with the changes marked, call GET /reconciliation (or /snapshots/fills, /snapshots/accounts) with includeReverted=true.
account.trading_day_revert_undone: the reverse, sent for each account an undo restores. The revert block has batchId, undone: true, undoReason, initiatedBy, undoneAt, revertedTo, affectedTradingDays, the balances and statuses before and after, snapshots (action: "restored") and restoredFillCount / restoredFills / restoredFillsTruncated (at most 500 inline; the rest count again too — re-read the affected days).
Both are part of a ["*"] subscription. Use POST /webhooks/{webhookId}/simulate to receive a sample of either.
snapshot.ready: fires once per organization per trading day, as soon as that day’s end-of-day snapshots are available (shortly after CME close, 16:00 CT). Payload:
{
"id": "evt_2c1d...",
"type": "snapshot.ready",
"organizationId": "a6fcc0ce-...",
"data": {
"tradingDay": "2026-07-22",
"accountsSnapshotted": 142,
"snapshotsUrl": "/platform/v1/organization/snapshots/accounts?tradingDay=2026-07-22",
"fillsUrl": "/platform/v1/organization/snapshots/fills?tradingDay=2026-07-22"
}
}
On receipt, call GET /snapshots/accounts?tradingDay=... — the data is guaranteed to be there. If you prefer polling, the snapshots endpoint also returns latestCompletedTradingDay.
Risk events (risk.*): the daily risk reports are computed once per trading day after the session closes (evening, Chicago time). risk.report_ready carries tradingDay, the status and row count of each report and reportUrl. Each finding event carries tradingDay, report, accounts (accountId, your customerId, traderId), finding (the same row as the daily report, same id) and reportUrl. Event ids are stable: the same finding always has the same event id, so dedupe on it. At most 200 finding events per type per day; the daily report always has every row. After an outage, list missed deliveries with GET /webhook-deliveries and replay them with POST /webhook-deliveries/{deliveryId}/redeliver, or read any day again with GET /risk/reports/{tradingDay}.
{
"id": "5d0c2a9e-41b7-5c3e-9a1f-2b7c8d9e0f12",
"type": "risk.hedge_pair_flagged",
"organizationId": "a6fcc0ce-...",
"data": {
"tradingDay": "2026-11-12",
"report": "hedge_pairs",
"accounts": [
{ "accountId": "7c9e6679-...", "customerId": "cust-4471", "traderId": "2b1f0c9e-..." },
{ "accountId": "9d1e6679-...", "customerId": "cust-5120", "traderId": "8a2e1d0f-..." }
],
"finding": { "id": "f3b1...", "underlying": "NQ", "overlapSeconds": 412, "legs": [ { "side": "long", "contract": "NQZ6", "size": 1, "pnl": 1250 }, { "side": "short", "contract": "MNQZ6", "size": 1, "pnl": -1310 } ] },
"reportUrl": "/platform/v1/organization/risk/reports/2026-11-12?report=hedge_pairs"
}
}
trader.signed_in: one event per sign-in of a trader who holds an account with you, sent within seconds. data: userId, signedInAt, method (password, oauth or mfa_totp), ipAddress, country, userAgent, deviceId, clientApp and clientVersion (null when the app did not send them), hostingNetwork (true when the address belongs to a hosting or VPN network, null when unknown) and accounts (accountId, accountNumber, your customerId, status, traderId). Only sign-ins from when the trader’s first account with you started, until 30 days after their last one ended.
fill.created: fires within seconds of an order reaching a terminal state with executed quantity — a complete fill (status: "filled"), or an order that partially executed and was then cancelled, rejected, or expired. Exactly one event per executed order, carrying the final totals: filledQuantity is the cumulative executed quantity (may be less than quantity for a final partial), filledPrice is the volume-weighted average across all executions of the order, and fee/commission/realizedPnl are the accumulated totals. Check status to distinguish a final partial from a complete fill; dedupe on orderId. (In the rare case an order recorded as cancelled or expired after a partial execution is later corrected to filled by the engine, a second event with the same orderId and updated totals is emitted, with the first totals in previousAttributes — treat the latest as authoritative. Its account.balance_changed carries only the difference to what was already announced.)
Requires explicit webhook subscription (never delivered via ["*"]; webhook event records only start once an active endpoint lists it). The same events always stream over the WebSocket at /organization/events/stream regardless of webhook configuration — see that endpoint for its delivery guarantees. Expect one event per executed order per account, so size your endpoint for your real fill rate. Payload:
{
"id": "evt_9f3a...",
"type": "fill.created",
"organizationId": "a6fcc0ce-...",
"data": {
"orderId": "0d1e...",
"contract": "MNQZ6",
"product": "MNQ",
"symbol": "MNQ",
"side": "buy",
"orderType": "market",
"status": "filled",
"quantity": 2,
"filledQuantity": 2,
"filledPrice": 21150.25,
"fee": 0.74,
"commission": 0.5,
"realizedPnl": null,
"filledAt": "2026-07-22T14:03:11.482Z",
"account": { "id": "...", "accountNumber": "ACME-1042", "customerId": "your-customer-id", "status": "in_progress", "currentBalance": 104250 },
"trader": { "email": "trader@example.com", "externalUserId": "your-user-id" }
}
}
A partial-then-cancelled order looks like "status": "cancelled", "quantity": 3, "filledQuantity": 1 — one contract really executed (balance, P&L, and fees reflect it), so record it as a fill of 1.
Payout events: account.payout_processed fires on every executed payout with the amounts and options applied in a payout block:
{
"id": "evt_7b2c...",
"type": "account.payout_processed",
"data": { "id": "...", "status": "in_progress", "...": "..." },
"payout": {
"payout_id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
"amount": 1600.0,
"balance_before": 52500.0,
"balance_after": 50900.0,
"payout_count": 1,
"mll_locked_to": 50100.0,
"consistency_reset": true
}
}
account.max_payouts_reached fires once, alongside the payout that hits the rule’s maxPayouts limit, carrying payout.payout_id and payout.payout_count.
account.payout_reversed fires when a payout is reversed (balance credited back). Its payout block carries payout_id, amount, balance_before/balance_after of the reversal, the new payout_count, cycle_starting_balance_shifted, and the original_payout details.
account.imported carries trigger (import_key or claim_email) and an import block. import.loginAlreadyBoundToOtherCustomer is true when, at the moment of this import, the Hyperprop login that imported the account was already bound to a different customerId of your organization (one login now holds accounts of two or more of your customers). import.otherBoundCustomerIds lists those other customerIds (your own IDs, oldest binding first, up to 10; empty when the flag is false). The import is not refused for this; the flag lets you review shared logins with GET /trader-bindings?email=.... Bindings at other organizations are never counted, and a login bound only to this account’s customerId gets false. Once a login is shared, every later import by it reports true and lists the other customers, including imports for a customer it already holds. Both fields are null when this could not be determined (for example on events recorded before the fields existed), so treat null as unknown rather than false. Payload:
{
"id": "evt_4d2e...",
"type": "account.imported",
"organizationId": "a6fcc0ce-...",
"trigger": "import_key",
"data": { "id": "ddf46c59-...", "customerId": "cust-2041", "status": "not_started", "...": "..." },
"previousAttributes": { "userId": null },
"import": {
"importKey": "HP-7K3QF-9XT2M-4WHRD",
"importedUserId": "2b8c1f0e-...",
"importedEmail": "trader@example.com",
"importedAt": "2026-10-17T11:02:45.120Z",
"loginAlreadyBoundToOtherCustomer": true,
"otherBoundCustomerIds": ["cust-1877"]
}
}
account.time_limit_extended carries trigger: "time_limit_extension" and a timeLimit block: maxAccountDays, extensionDays, totalDays (the new limit), dayNumber (the day it was decided, counting the activation day as day 1), activatedOn, originalLastDay and newLastDay (dates; the account fails at the close of its last day if it has not passed), totalProfit, profitTarget, minProgressPct, progressThreshold (dollars total profit had to be above) and extendedAt. If the account has not passed by newLastDay it fails with account.failed, ruleType time_limit_exceeded, as without an extension.
account.daily_loss_limit_off and account.daily_loss_limit_on carry trigger: "daily_loss_off_threshold" and a dailyLossLimit block: active (false when switched off, true when back on), dailyLoss, threshold, mode (while_above or permanent; null when the rule no longer sets a threshold), initialBalance, targetBalance (initial balance + threshold; null when the rule no longer sets one), eodBalance (the end-of-day balance judged), closingDay (the trading day that closed) and changedAt. Each change fires once per account.
account.balance_adjusted carries trigger: "balance_adjustment", the account in data, previousAttributes.currentBalance and a balanceAdjustment block: adjustmentId, reference (yours), type (credit or debit), amount (signed), reason, metadata (as you sent it, or null), balanceBefore, balanceAfter, countTowardDailyPnl, moveHighWaterMark and appliedAt. Match it to your record on reference.
account.claim_refused carries trigger: "claim_email" and a claimRefusal block: code (TRADER_ALREADY_BOUND or TRADER_DECLINED), message (what happened and what you can do), claimEmail, attemptedUserId (the Hyperprop user that tried to claim; null for TRADER_DECLINED), bindingId (your binding for this customerId) and refusedAt. The claim is retried every time the signed-in user is loaded (whenever the Hyperprop app opens, or on GET /platform/v1/auth/me), so the same refusal would recur on each visit; it is sent once per account, refusal code and user. To resolve it, ask the customer to sign in with the login they are bound to, or move the customer to the login that tried with POST /trader-bindings/{bindingId}/rebind and { "email": claimEmail }, after which the account links the next time that login is loaded (when they next open the app, or on POST /platform/v1/user/trading-accounts/claim-pending). The sign-in call alone does not link it. Unverified emails, emails that match no account and Hyperprop organization team logins never produce this event.
account.lockout_created and account.lockout_updated carry a top-level lockout block (id, mode, reason, cause, starts_at, ends_at), and data.activeLockout (the lockout in force when the event was recorded) also has cause. cause is a stable machine-readable value, so you do not need to parse reason: best_day_stop, daily_profit_target, daily_loss, daily_drawdown, max_loss, max_drawdown, session_window, trading_hours, trader_self_lock, admin, payout or other (see GET /lockouts). It is null when not recorded, for example on lockouts applied before the field existed; treat an unknown value like other.
data.tradingRule includes drawdownDenomination (percent by default, or dollars: maxDrawdown is then a dollar amount) and drawdownTrailCeiling (dollars above the initial balance where a trailing floor stops moving; null = trails forever), as on the trading-rules endpoints.
Limits: Maximum 5 webhooks per organization.
Delivery, retries and rate limits: answer with a 2xx within 10 seconds. Any other answer, a timeout or a connection error is a failed attempt; each event is tried up to 5 times over about 2.5 hours (after 1 min, 5 min, 30 min and 2 h). If your endpoint is rate-limited, answer 429 (or 503 with a Retry-After header): we wait as long as Retry-After asks (at most 5 minutes; without it 5 seconds, doubling while 429s continue), send to that endpoint more slowly, and speed up again as deliveries succeed. These answers never count as failures and never use up an event’s attempts; an event that only ever gets rate-limit answers is given up after 24 hours. Deliveries waiting this way show status: "retrying" with nextRetryAt.
Suspension and emails: an endpoint is suspended (isActive: false, with disabledAt and disabledReason) only after every delivery to it has failed for 24 hours in a row, with at least 50 failed attempts; one successful delivery ends the outage. Your firm’s admins (members who can manage the team or settings) get an email when an endpoint has failed for an hour, once per outage, and another when it is suspended. To resume, re-enable it with PATCH ({ "isActive": true }); missed events are then sent again (see Update a webhook). You can also catch up with GET /platform/v1/organization/balances?updatedSince= and the event stream’s ?since= replay.
Payload format: Each event includes the full trading account object (data) plus previousAttributes showing what changed. Where available, data includes event-time account context such as trader, trading plan, trading rule, purchase, and active lockout details. See the webhook documentation for full payload schemas.
Rule violation alerts: Subscribe to account.failed to be alerted the moment the trading engine fails an account. Violation events carry structured context:
| Field | Description | Example |
|---|---|---|
trigger | What caused the event | rule_violation, profit_target, admin_bulk |
ruleType | Which rule fired (rule violations only) | max_loss, max_drawdown, time_limit_exceeded (rule maxAccountDays), inactivity (rule maxInactiveDays) |
data.violationReason | Human-readable explanation | "Max Loss exceeded: $2514.00 loss >= $2500 limit" |
Failures made by your team (trigger: "admin_bulk") carry no ruleType. New values may be added; treat an unknown ruleType as a failure all the same.
{
"id": "evt_5f8a...",
"type": "account.failed",
"trigger": "rule_violation",
"ruleType": "max_loss",
"data": { "id": "...", "status": "failed", "violationReason": "Max Loss exceeded: $2514.00 loss >= $2500 limit", "...": "..." },
"previousAttributes": null
}
Daily loss and daily drawdown are not failures. When an account breaches its daily loss or daily drawdown limit, its open positions are closed, working orders are cancelled and the account is locked until the next trading day. It stays in_progress, so no account.failed or account.status_changed is sent, and the lock does not send account.lockout_created. Read the lock with GET /lockouts/ (or GET /lockouts for all active locks): mode is trading_day, cause is daily_loss or daily_drawdown, and endsAt is 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.
Signature verification:
const crypto = require('crypto');
function verify(rawBody, signature, secret, timestamp) {
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false; // replay protection
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(timestamp + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
Authentication: send your organization API key in the X-API-Key header.
Access: full-access API keys only (a read-only key gets 403 READ_ONLY_KEY). Dashboard members need manage access to Webhooks.
curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/webhooks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "https://your-server.com/webhooks/hyperprop",
"events": [
"account.created",
"account.status_changed"
],
"description": "Production webhook"
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/webhooks"
payload = {
"url": "https://your-server.com/webhooks/hyperprop",
"events": ["account.created", "account.status_changed"],
"description": "Production webhook"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://your-server.com/webhooks/hyperprop',
events: ['account.created', 'account.status_changed'],
description: 'Production webhook'
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://your-server.com/webhooks/hyperprop',
'events' => [
'account.created',
'account.status_changed'
],
'description' => 'Production webhook'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperprop.com/platform/v1/organization/webhooks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "d2f3a1c0-8e7b-4f6a-9c5d-1234567890ab",
"url": "https://your-server.com/webhooks/hyperprop",
"events": [
"account.created",
"account.status_changed"
],
"description": "Production webhook",
"isActive": true,
"failureCount": 0,
"disabledAt": "2026-03-28T22:00:00.000Z",
"disabledReason": "Suspended automatically: every delivery failed for 24 hours (412 failed attempts since 2026-03-27 21:58 UTC). Turn it back on to resume deliveries.",
"lastTriggeredAt": "2026-03-28T21:30:00.000Z",
"createdAt": "2026-03-28T21:00:00.000Z",
"updatedAt": "2026-03-28T21:30:00.000Z",
"secret": "whsec_your_signing_secret_here"
},
"message": "Webhook created. Save your signing secret — it won't be shown again."
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "Maximum 5 webhooks per organization",
"code": "WEBHOOK_LIMIT_REACHED"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Access denied",
"code": "FORBIDDEN"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Service Unavailable",
"message": "The Idempotency-Key could not be recorded, so the request was not run. Retry with the same key.",
"code": "IDEMPOTENCY_UNAVAILABLE"
}Authorizations
Organization API key (hp_live_...), sent in the X-API-Key header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A full-access key can call every endpoint in this reference. A read-only key can call GET endpoints (and create a trading stream token); any other request returns 403 READ_ONLY_KEY. A key with an IP allowlist returns 403 IP_NOT_ALLOWED from any other address. Each endpoint lists which keys can call it under Access.
Headers
Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with Idempotency-Replayed: true) instead of repeating the change. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. A response that contains a credential (such as a new API key or signing secret) is not saved: the change is still not repeated, and a retry returns 409 IDEMPOTENCY_KEY_COMPLETED with the original status in originalStatus. Server errors (5xx) are not saved, so a retry runs again. If the key cannot be recorded, the request is not run and returns 503 IDEMPOTENCY_UNAVAILABLE; retry with the same key.
255Body
Event types to subscribe to. Use ["*"] for all current and future events.
1*, account.created, account.status_changed, account.updated, account.imported, account.unlinked, account.passed, account.failed, account.lockout_created, account.lockout_removed, account.lockout_updated, account.payout_processed, account.max_payouts_reached, account.payout_reversed, account.time_limit_extended, account.daily_loss_limit_off, account.daily_loss_limit_on, account.claim_refused, purchase.created, purchase.status_changed, trader.created, snapshot.ready, fill.created, account.balance_changed, account.balance_adjusted, account.trading_day_reverted, account.trading_day_revert_undone, risk.report_ready, risk.hedge_pair_flagged, risk.copy_trading_flagged, risk.shared_device_flagged, trader.signed_in, alert.limit_crossed, alert.limit_cleared ["account.created", "account.status_changed"]
curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/webhooks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "https://your-server.com/webhooks/hyperprop",
"events": [
"account.created",
"account.status_changed"
],
"description": "Production webhook"
}
'import requests
url = "https://api.hyperprop.com/platform/v1/organization/webhooks"
payload = {
"url": "https://your-server.com/webhooks/hyperprop",
"events": ["account.created", "account.status_changed"],
"description": "Production webhook"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://your-server.com/webhooks/hyperprop',
events: ['account.created', 'account.status_changed'],
description: 'Production webhook'
})
};
fetch('https://api.hyperprop.com/platform/v1/organization/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://your-server.com/webhooks/hyperprop',
'events' => [
'account.created',
'account.status_changed'
],
'description' => 'Production webhook'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperprop.com/platform/v1/organization/webhooks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://your-server.com/webhooks/hyperprop\",\n \"events\": [\n \"account.created\",\n \"account.status_changed\"\n ],\n \"description\": \"Production webhook\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "d2f3a1c0-8e7b-4f6a-9c5d-1234567890ab",
"url": "https://your-server.com/webhooks/hyperprop",
"events": [
"account.created",
"account.status_changed"
],
"description": "Production webhook",
"isActive": true,
"failureCount": 0,
"disabledAt": "2026-03-28T22:00:00.000Z",
"disabledReason": "Suspended automatically: every delivery failed for 24 hours (412 failed attempts since 2026-03-27 21:58 UTC). Turn it back on to resume deliveries.",
"lastTriggeredAt": "2026-03-28T21:30:00.000Z",
"createdAt": "2026-03-28T21:00:00.000Z",
"updatedAt": "2026-03-28T21:30:00.000Z",
"secret": "whsec_your_signing_secret_here"
},
"message": "Webhook created. Save your signing secret — it won't be shown again."
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "Maximum 5 webhooks per organization",
"code": "WEBHOOK_LIMIT_REACHED"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Access denied",
"code": "FORBIDDEN"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "This Idempotency-Key was already used with a different request body. Use a new key for a different request.",
"code": "IDEMPOTENCY_KEY_REUSED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Service Unavailable",
"message": "The Idempotency-Key could not be recorded, so the request was not run. Retry with the same key.",
"code": "IDEMPOTENCY_UNAVAILABLE"
}