PhoenixPerpetualsDocs API v1
Get an API key

Trading

Webhooks⁠.

Your server told the moment something happens on your accounts: signed deliveries, retries, chat formats, and how to check every one.

View as Markdown

On this page
  1. Create an endpoint
  2. What arrives
  3. Check every delivery
  4. Answer fast, then work
  5. When an endpoint keeps failing
  6. Test and replay

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-types lists 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: json for your code, or discord, slack or telegram for 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:

HeaderWhat it is
X-Phoenix-Signaturesha256= 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-TimestampWhen it was signed, in Unix seconds
X-Phoenix-Event, X-Phoenix-Event-IdThe event's type and id
X-Phoenix-Delivery, X-Phoenix-AttemptThis 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 out
from phoenixperps import Webhooks

event = Webhooks.verify(raw_body, headers, os.environ["PHOENIXPERPS_WEBHOOK_SECRET"])  # raises when it does not check out
event, 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}/test sends a webhook.ping event 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}/deliveries lists the last 7 days of deliveries with each attempt's status and timing, and POST .../deliveries/{delivery_id}/resend sends one again, with the same event id and marked "test": true (a trade key too). An attempt answered with an error status shows it as http_<status>.

Guides, endpoints, fields and error codes.