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.
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:
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:
- Refuse a timestamp more than 5 minutes away from your clock (replay protection).
- Compute HMAC-SHA256(secret, timestamp + "." + raw body) as lowercase hex and prefix it with v1=.
- Compare it in constant time with the value of x-gw-signature (one
v1=…entry). Afterrotate-secretthe 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 newdeliveryIdand 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
});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:
| Type | Meaning | Fields |
|---|---|---|
ORDER_UPDATE | Positions 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_ADDED | A new deal in the account history. | dealId, positionId, time, dealType, entryType, late (true: found behind an earlier sync point) |
COMMAND_FINISHED | A trade or check command finished. | commandId, commandType, status (SUCCEEDED, FAILED, CANCELLED), errorCode |
ACCOUNT_STATE_CHANGED | The runtime state of an account changed. | from, to (runtimeState), reason |
AUTH_REJECTED | The broker rejected a password of the account. | which (master or investor) |
HISTORY_SYNCED | The account's full history download finished (once). | syncedUntil |
WATCH_TRIGGERED | An equity watch set with PUT /v1/accounts/{id}/watches fired. | watch, version, kind, threshold, equity, balance, at |
MAIL_RECEIVED | A new message in the terminal's mailbox. | mailId, time, from, subject, body |
RISK_LIMIT_BREACHED | A risk tracker's drawdown limit was reached (once per period). | tracker, name, period, periodStart, periodEnd, base, equity, balance, drawdown, drawdownPct, action |
RISK_TARGET_REACHED | A risk tracker's profit target was reached. | tracker, name, period, periodStart, periodEnd, base, equity, balance, profit, profitPct |
DAILY_DRAWDOWN_BREACHED | The 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_OPENED | Copy trading opened a copy on the master account. | allocation, leaderPosition, masterPosition, reason |
COPY_CLOSED | Copy trading closed a copy. | allocation, leaderPosition, masterPosition, reason |
COPY_SKIPPED | Copy trading skipped a trade (filters, limits). | allocation, leaderPosition, masterPosition, reason |
COPY_FAILED | Copy trading could not copy a trade. | allocation, leaderPosition, masterPosition, reason |
COPY_MODIFIED | The copy's stop loss / take profit followed the leader (sent once the master confirmed the change). | allocation, leaderPosition, masterPosition, sl, tp, version |
SERVER_TZ_MISMATCH | The broker server of one of your accounts changed its clock rule; broker-time figures may shift until it is corrected. | server, observed, rule |
SUBSCRIPTION_EXPIRING | Your plan ends in 3 days / 1 day. | expiresAt, daysLeft |
SUBSCRIPTION_EXPIRED | Your plan ended. | expiresAt, graceEndsAt (ACTIVE accounts go STANDBY then) |
WEBHOOK_DISABLED | A 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_TEST | Sent 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.
# 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 }'