Webhook payload reference

The webhook endpoint accepts JSON alert events for research and post-hoc reconciliation. A successful request records the event and a normalized trade-order row. It does not submit an order to a broker.

Endpoint URLs are created in the app and use the Algo Trade Analytics host:

https://app.algo-trade-analytics.com/api/webhooks/<webhook-key>

Use the exact URL and auth_key shown for that webhook connection. The key in the URL identifies the connection; the key in the JSON body authenticates the payload.

Minimum accepted payload

Every payload needs:

Requirement	Accepted field
Authentication	non-empty `auth_key`
Symbol	non-empty `ticker`
Position intent	`positionDirection`, `positionIntent`, or `direction`
Size	exactly one of positive `qty` or positive `notional`

The simplest TradingView format uses positionDirection. The server derives direction and side from it.

{
  "auth_key": "YOUR_AUTH_KEY",
  "ticker": "AAPL",
  "positionDirection": "entryLong",
  "qty": 10
}

positionDirection must be one of:

entryLong
exitLong
entryShort
exitShort

Recommended analytics fields

These fields are not all required for ingestion, but they make comparisons less ambiguous:

Field	Type	Purpose
`strategy`	string	Keeps events from different strategies on the same symbol separate.
`marketPrice`	positive number	Records the price context at signal generation.
`orderType`	string	Identifies market, limit, stop, stop-limit, or trailing-stop intent.
`metadata.timestamp`	ISO-8601 string	Preserves signal time instead of using server receipt time.
`metadata.signal`	string	Adds a human-readable reason or event label.

metadata.strategy is also accepted. When both forms exist, the top-level strategy value takes precedence.

Order types and conditional fields

If orderType is omitted, the server infers it from the price fields and otherwise uses market.

`orderType`	Additional validation
`market`	No order-price field required.
`limit`	Positive `limitPrice` required.
`stop`	Positive `stopPrice` required. A legacy stop payload may fall back to `marketPrice`.
`stop_limit`	Positive `stopPrice` and `limitPrice` required. For long intent, stop must be below limit; for short intent, stop must be above limit.
`trailing_stop`	Exactly one of `trailPrice` or `trailPercent` is preferred. If both are sent, percent takes precedence and the response includes a warning.

Optional execution-context fields include timeInForce, extendedHours, clientOrderId, accountId, takeProfit, and stopLoss. They are stored as event context; the webhook endpoint remains non-executing.

Tested examples

The documentation test suite sends every JSON block in this section through the same normalizer and validator used by the webhook endpoint.

Market entry

{
  "auth_key": "YOUR_AUTH_KEY",
  "ticker": "AAPL",
  "positionDirection": "entryLong",
  "orderType": "market",
  "qty": 100,
  "marketPrice": 150.5,
  "strategy": "MA Crossover",
  "metadata": {
    "timestamp": "2026-07-14T14:30:00.000Z",
    "signal": "Golden Cross"
  }
}

Long stop-limit entry

{
  "auth_key": "YOUR_AUTH_KEY",
  "ticker": "SPY",
  "positionDirection": "entryLong",
  "orderType": "stop_limit",
  "qty": 25,
  "marketPrice": 419.5,
  "stopPrice": 420,
  "limitPrice": 420.5,
  "strategy": "Breakout",
  "metadata": {
    "timestamp": "2026-07-14T14:31:00.000Z",
    "signal": "Range Break"
  }
}

Trailing-stop exit

{
  "auth_key": "YOUR_AUTH_KEY",
  "ticker": "TSLA",
  "positionDirection": "exitLong",
  "orderType": "trailing_stop",
  "qty": 10,
  "marketPrice": 310.25,
  "trailPercent": 2,
  "strategy": "Trend Follow",
  "metadata": {
    "timestamp": "2026-07-14T14:32:00.000Z",
    "signal": "Trailing Exit"
  }
}

TradingView order-fill setup

When the Pine strategy builds the JSON in an order command’s alert_message, set TradingView’s alert Message field to:

{{strategy.order.alert_message}}

TradingView substitutes the message when its broker emulator fills the strategy order. Keep every order path that should emit an alert wired to alert_message; otherwise that order can produce an empty alert body.

See Configure TradingView webhooks for the full setup sequence and Supported strategy patterns for direction and multi-leg guidance.

Responses and limits

Invalid JSON returns 400.
A missing or incorrect auth_key returns 401.
An inactive or unknown webhook URL returns 404.
A rate, monthly-event, or active-endpoint limit returns 429.
A JSON body larger than 128 KB returns 413.

New webhook connections default to 30 requests per 60-second window. The app stores the rate window and maximum per connection, so use the values shown in the product if they have been changed.