# Webhooks

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

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](/guides/streams) 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](/guides/alerts) 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](/guides/streams) show, with the endpoint's `api_version` and `environment`:

```json
{
  "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](/reference/webhook-events).

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:

```typescript
import { Webhooks } from "@phoenixperps/sdk";

const event = Webhooks.verify(rawBody, req.headers, process.env.PHOENIXPERPS_WEBHOOK_SECRET!); // throws when it does not check out
```

```python
from phoenixperps import Webhooks

event = Webhooks.verify(raw_body, headers, os.environ["PHOENIXPERPS_WEBHOOK_SECRET"])  # raises when it does not check out
```

```go
event, err := phoenixperps.VerifyWebhook(rawBody, r.Header, []string{os.Getenv("PHOENIXPERPS_WEBHOOK_SECRET")}, 5*time.Minute)
```

```csharp
var e = Webhooks.Verify(rawBody, headers, Environment.GetEnvironmentVariable("PHOENIXPERPS_WEBHOOK_SECRET")!);
```

```java
WebhookPayload event = Webhooks.verify(rawBody, headers, System.getenv("PHOENIXPERPS_WEBHOOK_SECRET"));
```

```rust
let event = phoenixperps::verify_webhook(&raw_body, headers, &[secret.as_str()], None, None)?;
```

```php
$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>`.
