Trading
Webhooks.
Your server told the moment something happens on your accounts: signed deliveries, retries, chat formats, and how to check every one.
On this page
A webhook endpoint is an address of yours that we call when something happens on your accounts: an order fills, a position closes, an account passes, a loss limit comes close. Where the account stream needs your code to stay connected, a webhook reaches a server that only wakes up to answer.
Create an endpoint#
In your dashboard, open Developers, Webhooks and choose Add endpoint. Give it:
- The address:
https, on port 443, on the public internet. We never call a private or local address, and never follow a redirect. - The environment: live or sandbox, for life. A live endpoint takes a code we email you.
- The events, by group: orders (orders, fills, strategies, TradingView alerts), positions, account (balance and status, passed, failed, payout eligible, disabled or removed, a key's daily loss stop, a key about to expire, an engine restart), risk (a warning as a limit comes close, and when it goes) and alerts (a price alert fired).
GET /v1/webhook-event-typeslists every type with what it means. Events are those of the accounts the API follows: the ones your keys use, your streams follow, or a key's daily loss stop watches. - The format:
jsonfor your code, ordiscord,slackortelegramfor a chat message instead.
You can keep 5 endpoints in each environment. The signing secret (ppwhsec_...) is shown once, when you create the endpoint: keep it in your server's secrets. To change it, add a new endpoint for the same address, move your server to its secret, then delete the old one.
What arrives#
A json endpoint receives one POST per event: the same event GET /v1/events and the account stream show, with the endpoint's api_version and environment:
{
"id": "evt_01JAB7Q8XK4M2N5P7R9S3T5V7W",
"type": "order.filled",
"account_id": "SANDBOX-00042-001",
"time": 1791460800123,
"source": "api",
"data": { "order": { "id": "ord_01JAB7Q8XK4M2N5P7R9S3T5V7W", "market": "BTC-USD", "side": "buy", "status": "filled", "average_fill_price": "62510.0" } },
"api_version": "v1",
"environment": "sandbox"
}The SDKs' signature check answers it as their WebhookPayload type (an event, with its environment and test flag; account_id is absent on webhook.ping). Every event type, with what it means, is in the webhook events reference.
with these headers:
| Header | What it is |
|---|---|
X-Phoenix-Signature | sha256= and the hex HMAC-SHA256 of <timestamp>.<raw body> with your secret. It can hold several values, comma-separated: one that checks out is enough |
X-Phoenix-Timestamp | When it was signed, in Unix seconds |
X-Phoenix-Event, X-Phoenix-Event-Id | The event's type and id |
X-Phoenix-Delivery, X-Phoenix-Attempt | This delivery's id and its attempt number |
A chat format receives the event as one short sentence instead (Discord {content}, Slack {text}, Telegram {chat_id, text}, the chat taken from your address's chat_id), unsigned: point those at the chat's own webhook address.
Check every delivery#
Anyone can send a request to your address. Before you trust a delivery, check its signature and its time against your secret, on the body exactly as it arrived (before any JSON parsing). Every SDK does it in one call:
import { Webhooks } from "@phoenixperps/sdk";
const event = Webhooks.verify(rawBody, req.headers, process.env.PHOENIXPERPS_WEBHOOK_SECRET!); // throws when it does not check outfrom phoenixperps import Webhooks
event = Webhooks.verify(raw_body, headers, os.environ["PHOENIXPERPS_WEBHOOK_SECRET"]) # raises when it does not check outevent, err := phoenixperps.VerifyWebhook(rawBody, r.Header, []string{os.Getenv("PHOENIXPERPS_WEBHOOK_SECRET")}, 5*time.Minute)var e = Webhooks.Verify(rawBody, headers, Environment.GetEnvironmentVariable("PHOENIXPERPS_WEBHOOK_SECRET")!);WebhookPayload event = Webhooks.verify(rawBody, headers, System.getenv("PHOENIXPERPS_WEBHOOK_SECRET"));let event = phoenixperps::verify_webhook(&raw_body, headers, &[secret.as_str()], None, None)?;$event = PhoenixPerps\Webhooks::verify($rawBody, $headers, getenv('PHOENIXPERPS_WEBHOOK_SECRET'));A delivery older than 5 minutes is refused as stale, so a recorded one cannot be played back to you later.
Answer fast, then work#
Answer with any 2xx within 5,000 ms, then do the work: put the event on a queue rather than trading from inside the request. Anything else (an error, a timeout, a redirect) counts as a failure and the delivery is tried again after 30, 120, 600, 1800, 3600, 7200, 14400 and 28800 seconds, a little earlier or later each time. A Retry-After in your answer is honored, up to an hour.
- Once per event, at least once. A retry carries the same
X-Phoenix-Event-Id: keep the ids you processed and skip one you have seen. - In order, per endpoint. While an endpoint is healthy, its deliveries go one after the other in the order of the events.
- Never history. A new endpoint receives what happens from then on, never past events: read those from
GET /v1/events.
When an endpoint keeps failing#
An endpoint that fails for 24 hours with at least 10 failures in a row, or that answers 410 Gone, is disabled: its waiting deliveries are dropped and we email you. Fix the receiver, then turn the endpoint back on in the dashboard or with POST /v1/webhook-endpoints/{id}/enable: from the answer on, deliveries go again (an enable after the disabling always wins). Pausing an endpoint (.../disable) keeps its deliveries waiting until you resume it; it applies from the answer on too.
Test and replay#
POST /v1/webhook-endpoints/{id}/testsends awebhook.pingevent to the endpoint, signed like any other, marked"test": true. It calls your server, so it takes a trade key (or app).GET /v1/webhook-endpoints/{id}/deliverieslists the last 7 days of deliveries with each attempt's status and timing, andPOST .../deliveries/{delivery_id}/resendsends one again, with the same event id and marked"test": true(a trade key too). An attempt answered with an error status shows it ashttp_<status>.