API documentation

Webhooks

Webhooks push your events to an HTTPS endpoint as they happen — signed, in order and at least once — so you do not have to poll.

Updated

Create a webhook

POST /v1/webhooks with your URL (needs the manage permission). Leave eventTypes out to receive every event, and accountIds out to cover every account.

bash
curl -X POST https://api.propmetaapi.com/v1/webhooks \
  -H "Authorization: Bearer $GW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/mt-hook",
    "description": "orders to my backend",
    "eventTypes": ["ORDER_UPDATE", "DEAL_ADDED", "SUBSCRIPTION_EXPIRING"]
  }'
# 201 → { "id": "…", "url": "…", "enabled": true, "eventTypes": [...], "secret": "whsec_…", … }   the secret is shown once
  • The URL must be https on a public host (no private-network address), without user name / password or #fragment, on port 443, 80 or 1024 and above — well-known service ports (databases, RDP, VNC, proxies and the like) are refused, as for ping-host. Redirects are not followed.
  • The answer (201) contains the signing secret (whsec_…) — it is shown only now and after a rotation.
  • A new webhook receives the events that happen after its creation. Up to 10 webhooks per customer.
  • A key limited to some accounts can only create and see webhooks for those accounts. Events without an account (plan notices, WEBHOOK_DISABLED, SERVER_TZ_MISMATCH) go to every webhook whose eventTypes allow them.

What you receive

Each delivery is a POST with a JSON body holding up to 50 events, oldest first:

http
POST /mt-hook HTTP/1.1
Content-Type: application/json
x-gw-webhook-id: 6d1e…
x-gw-delivery: 0b7a…
x-gw-timestamp: 1767225600
x-gw-signature: v1=5f2c…e9
User-Agent: PropMetaAPI-Webhooks/1

{
  "webhookId": "6d1e…",
  "deliveryId": "0b7a…",
  "sentAt": "2026-01-01T00:00:00.000Z",
  "events": [
    { "id": "1842", "type": "ORDER_UPDATE", "accountId": "3f0c…", "occurredAt": "2026-01-01T00:00:00.000Z", "updateType": "POSITION_OPENED", "ticket": "50123", "symbol": "EURUSD", … }
  ]
}
  • Answer any 2xx within 10 seconds to acknowledge; the next batch follows at once. Do slow work after answering.
  • Delivery is in event-id order and at least once: deduplicate on the event id (ids are strings of increasing numbers).
  • On failure (non-2xx, timeout, connection error) the same batch is retried after 10 s, 20 s, 40 s … up to 1 hour between attempts. A request that got no HTTP answer (connection refused or reset, TLS error, timeout) is shown as one error text, “no HTTP answer from the URL …”; check your server's own logs for the cause.
  • A webhook failing for 72 hours is switched off (enabled: false, disabledReason) and a WEBHOOK_DISABLED event is emitted; switch it on again with PATCH { "enabled": true }. Events are kept 14 days, so a webhook that is off for longer misses the oldest ones.
  • While your plan is expired or your access suspended nothing is delivered; the waiting events follow after the renewal.

Verify the signature

Every request carries x-gw-timestamp (unix seconds) and x-gw-signature: v1=<hex HMAC-SHA256> computed with your secret over timestamp + "." + raw body. Check both before trusting the payload:

  1. Refuse a timestamp more than 5 minutes away from your clock (replay protection).
  2. Compute HMAC-SHA256(secret, timestamp + "." + raw body) as lowercase hex and prefix it with v1=.
  3. Compare it in constant time with the value of x-gw-signature (one v1=… entry). After rotate-secret the next deliveries are signed with the new secret only — deploy it on your receiver first; a delivery your receiver rejects is retried (10 s, doubling, for up to 72 h) with a new deliveryId and timestamp, and the retried batch may contain more events than the first attempt.
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const SECRET = process.env.GW_WEBHOOK_SECRET!; // whsec_…

function verify(rawBody: string, timestamp: string, signature: string): boolean {
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const want = Buffer.from("v1=" + createHmac("sha256", SECRET).update(`${ts}.${rawBody}`).digest("hex"));
  // x-gw-signature carries exactly one "v1=…" value; after rotate-secret the old secret stops signing at once
  return signature.split(",").some((s) => {
    const got = Buffer.from(s.trim());
    return got.length === want.length && timingSafeEqual(got, want);
  });
}

const app = express();
// the RAW body: re-serialised JSON would not match the signature
app.post("/mt-hook", express.text({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.get("x-gw-timestamp") ?? "", req.get("x-gw-signature") ?? "")) {
    return res.status(401).end();
  }
  const { events } = JSON.parse(req.body);
  for (const e of events) console.log(e.id, e.type);
  res.status(204).end(); // any 2xx moves the cursor
});
Check the signature over the raw request bytes. Frameworks that parse JSON first and re-serialise it change spacing and key order, and the signature will not match.

Event types

The same events arrive in the feed GET /v1/events and on the WebSocket events channel. Every event has id, type, accountId (null for events without an account) and occurredAt, plus the fields of its type:

TypeMeaningFields
ORDER_UPDATEPositions or pending orders changed (opened, modified, partially closed, closed, placed, filled, cancelled, expired) — one event per change.updateType (POSITION_OPENED, POSITION_MODIFIED, POSITION_PARTIALLY_CLOSED, POSITION_CLOSED, ORDER_PLACED, ORDER_MODIFIED, ORDER_PARTIALLY_FILLED, ORDER_FILLED, ORDER_CANCELLED, ORDER_EXPIRED), ticket (position id — MT4: root ticket — or order id), symbol, position? (the position after the change), order? (the order), previous? { volume, stopLoss, takeProfit, price }, at
DEAL_ADDEDA new deal in the account history.dealId, positionId, time, dealType, entryType, late (true: found behind an earlier sync point)
COMMAND_FINISHEDA trade or check command finished.commandId, commandType, status (SUCCEEDED, FAILED, CANCELLED), errorCode
ACCOUNT_STATE_CHANGEDThe runtime state of an account changed.from, to (runtimeState), reason
AUTH_REJECTEDThe broker rejected a password of the account.which (master or investor)
HISTORY_SYNCEDThe account's full history download finished (once).syncedUntil
WATCH_TRIGGEREDAn equity watch set with PUT /v1/accounts/{id}/watches fired.watch, version, kind, threshold, equity, balance, at
MAIL_RECEIVEDA new message in the terminal's mailbox.mailId, time, from, subject, body
RISK_LIMIT_BREACHEDA risk tracker's drawdown limit was reached (once per period).tracker, name, period, periodStart, periodEnd, base, equity, balance, drawdown, drawdownPct, action
RISK_TARGET_REACHEDA risk tracker's profit target was reached.tracker, name, period, periodStart, periodEnd, base, equity, balance, profit, profitPct
DAILY_DRAWDOWN_BREACHEDThe account's daily drawdown limit (PUT /v1/accounts/{id}/daily-drawdown) was reached (once per day, and once per start after a restart).restartId, periodStart, periodEnd, startBalance, startEquity, base, percentBase, equity, balance, cashFlow, drawdown, drawdownPct, limitPct, limitAbs, percentOf, resetTimezone, confirmSec, action, tracker, name, period
COPY_OPENEDCopy trading opened a copy on the master account.allocation, leaderPosition, masterPosition, reason
COPY_CLOSEDCopy trading closed a copy.allocation, leaderPosition, masterPosition, reason
COPY_SKIPPEDCopy trading skipped a trade (filters, limits).allocation, leaderPosition, masterPosition, reason
COPY_FAILEDCopy trading could not copy a trade.allocation, leaderPosition, masterPosition, reason
COPY_MODIFIEDThe copy's stop loss / take profit followed the leader (sent once the master confirmed the change).allocation, leaderPosition, masterPosition, sl, tp, version
SERVER_TZ_MISMATCHThe broker server of one of your accounts changed its clock rule; broker-time figures may shift until it is corrected.server, observed, rule
SUBSCRIPTION_EXPIRINGYour plan ends in 3 days / 1 day.expiresAt, daysLeft
SUBSCRIPTION_EXPIREDYour plan ended.expiresAt, graceEndsAt (ACTIVE accounts go STANDBY then)
WEBHOOK_DISABLEDA webhook failed for 72 hours, or its URL is no longer allowed, and was switched off. It reaches every webhook and key, so it names the webhook only by id: read its URL with GET /v1/webhooks/{id}.webhookId, failingSince, lastError (no URL or host name)
WEBHOOK_TESTSent only by POST /v1/webhooks/{id}/test (id "0", accountId null); not selectable in eventTypes.message

Test and monitor

Delivery status, the last error and the delivery log (kept 7 days) are also shown in Account → API → Webhooks.

bash
# send one WEBHOOK_TEST event now
curl -X POST https://api.propmetaapi.com/v1/webhooks/$WEBHOOK_ID/test -H "Authorization: Bearer $GW_KEY"

# last deliveries (status, error, duration)
curl https://api.propmetaapi.com/v1/webhooks/$WEBHOOK_ID/deliveries -H "Authorization: Bearer $GW_KEY"

# new secret (the old one stops signing at once)
curl -X POST https://api.propmetaapi.com/v1/webhooks/$WEBHOOK_ID/rotate-secret -H "Authorization: Bearer $GW_KEY"

# switch back on after it was disabled
curl -X PATCH https://api.propmetaapi.com/v1/webhooks/$WEBHOOK_ID -H "Authorization: Bearer $GW_KEY" \
  -H "Content-Type: application/json" -d '{ "enabled": true }'