TradingView Webhooks LLM Reference

# FutuCopy TradingView Webhooks LLM Reference

Last updated: 2026-05-07

This file is written for AI assistants and advanced users who need exact, user-facing details about the FutuCopy TradingView Webhooks feature. It describes the public behavior, supported JSON fields, TradingView placeholder usage, examples, validation rules, and troubleshooting guidance. It intentionally avoids private infrastructure details.

If a user gives you this file and asks for help, use it as the source of truth for FutuCopy webhook payloads. If the question is about TradingView's current placeholder behavior or alert UI, also consult TradingView's official help documentation:

- TradingView alert placeholders: https://www.tradingview.com/support/solutions/43000531021-how-to-use-a-variable-value-in-alert/
- TradingView Pine Script alerts FAQ: https://www.tradingview.com/pine-script-docs/faq/alerts/

If an AI assistant cannot fetch this raw Markdown file, use the HTML companion page instead:

- https://futucopy.com/tradingview-webhooks

If the user is asking where to click in FutuCopy, tell them to open the FutuCopy Webhooks page. The Webhooks page contains the webhook token, webhook URL, configured leaders, alert message builder, test webhook modal, and webhook call history.

## What The Feature Does

FutuCopy TradingView Webhooks lets a user send TradingView strategy alerts to FutuCopy. FutuCopy receives the alert, validates the user's webhook token, reads the JSON message, and then places or flattens orders on the selected trade copy leader configuration. If copy trading is enabled for that leader, follower accounts may also receive copied orders according to the user's copy configuration.

The public webhook endpoint is:

```text
https://webhook.futucopy.com/webhook/YOUR_WEBHOOK_TOKEN
```

Replace `YOUR_WEBHOOK_TOKEN` with the token shown on the user's FutuCopy Webhooks page.

## Security Model And Access

The public webhook URL is designed for TradingView webhook delivery. The endpoint is restricted so public calls should come from TradingView's webhook delivery servers. Other third-party apps should not be used to call the public webhook endpoint directly.

The webhook token is a secret. Anyone who can send a valid TradingView webhook to the URL with that token can trigger the configured webhook action. Users should rotate the token if they share it accidentally, expose it in a screenshot, paste it into a public script, or suspect unauthorized use.

The FutuCopy Webhooks page includes token management:

- Generate Webhook Token: creates a token and webhook URL.
- Rotate: creates a new token and invalidates the previous token.
- Delete: removes the token and disables webhook access.
- Copy buttons: copy the token or full webhook URL.

## FutuCopy UI Workflow

In FutuCopy:

1. Open the Webhooks page.
2. Generate a webhook token if one does not already exist.
3. Copy the full Webhook URL.
4. Review the Configured Leaders table. Each eligible leader has an ID. Use this ID as `leader_id` in webhook messages.
5. Use the Alert Message Builder to create JSON in either Manual or Pine Script mode.
6. Use Test Webhook only with Manual messages. Pine Script placeholders are filled by TradingView, so FutuCopy cannot fill them during a manual test.
7. Review Webhook Call History after alerts fire. It shows time, request body, status, response message, and errors.
8. Export Webhook Call History to CSV if the user needs to review or share logs.

The Webhooks page only shows leaders that have an assigned leader account as eligible. If no leaders appear, the user must configure a leader account on the Trade Copy page first.

## TradingView Requirements

TradingView webhooks require a TradingView plan that supports webhooks and two-factor authentication enabled on the TradingView account. In the FutuCopy UI this is summarized as: TradingView requires Essential plan or higher and 2FA enabled for webhooks.

For strategy placeholders like `{{strategy.order.action}}` and `{{strategy.order.contracts}}`, the alert must be a TradingView strategy order-fill alert, not a simple manual price alert.

## Supported Content Type

TradingView should send a JSON object in the alert message body. The webhook body must be valid JSON.

Recommended content:

```json
{
  "action": "buy",
  "contracts": 1,
  "leader_id": 1496,
  "order_type": "market"
}
```

The practical request body limit is 16 KB. FutuCopy logs the raw request body for troubleshooting, truncated at 10 KB.

## Supported Actions

The `action` field controls the webhook operation.

### Place Order

Supported values:

- `buy`
- `sell`

These place an order on the selected leader account. Required fields for order placement:

- `action`
- `contracts`
- `leader_id`

Optional order placement fields:

- `order_type`
- `orderType`
- `price`
- `stop_loss_ticks`
- `stop_loss_price`
- `stopLossPrice`
- `profit_target_ticks`
- `profit_target_price`
- `profitTargetPrice`

### Flatten One Leader

Supported values:

- `flatten`
- `flatten_leader`

Required fields:

- `action`
- `leader_id`

This flattens the selected leader's current position for the configured leader account and contract.

Example:

```json
{
  "action": "flatten",
  "leader_id": 1496
}
```

### Flatten All

Supported values:

- `flatten_all`
- `flattenall`

Required fields:

- `action`

This requests a flatten-all operation for the user. It does not require `leader_id`.

Example:

```json
{
  "action": "flatten_all"
}
```

## Supported JSON Fields

### `action`

Type: string

Required: yes

Supported values:

- `buy`
- `sell`
- `flatten`
- `flatten_leader`
- `flatten_all`
- `flattenall`

For TradingView strategy alerts, use:

```json
"action": "{{strategy.order.action}}"
```

TradingView replaces `{{strategy.order.action}}` with `buy` or `sell` for strategy order-fill alerts.

### `contracts`

Type: integer

Required: yes for `buy` and `sell`; ignored for flatten actions.

Validation: must be greater than zero.

For TradingView strategy alerts, use:

```json
"contracts": {{strategy.order.contracts}}
```

Do not put quotes around `{{strategy.order.contracts}}` when you want it to be JSON numeric output.

### `leader_id`

Type: integer

Required: yes for `buy`, `sell`, `flatten`, and `flatten_leader`; not required for `flatten_all`.

Validation: must be greater than zero and must match one of the user's configured eligible leaders.

Users can find leader IDs in the Configured Leaders table on the FutuCopy Webhooks page.

### `order_type`

Type: string

Required: no. Defaults to `market` when omitted.

Supported values:

- `market`
- `mkt`
- `1`
- `limit`
- `lmt`
- `2`
- `stop`
- `stp`
- `3`

Preferred values for documentation and examples:

- `market`
- `limit`
- `stop`

`orderType` is also accepted as a camelCase alias.

### `price`

Type: decimal number or numeric string

Required: required for `limit` and `stop` orders; must be omitted for `market` orders.

Validation:

- For `limit` or `stop`, `price` must be greater than zero.
- For `market`, `price` must not be included.

For TradingView strategy fill price, use:

```json
"price": {{strategy.order.price}}
```

Important: TradingView's `{{strategy.order.price}}` is the executed fill price of a strategy order-fill event. If the user wants a calculated stop or limit level before fill, they should create that value in Pine Script and send it through `alert_message`, then use `{{strategy.order.alert_message}}` in the TradingView alert.

### `stop_loss_ticks`

Type: integer

Required: no

Purpose: Adds a stop-loss distance in ticks from the entry price.

Validation:

- Must be at least 1 when included.
- Cannot be used at the same time as `stop_loss_price`.

Bracket parameters are intended for Tradovate leaders only in the FutuCopy UI.

### `stop_loss_price`

Type: decimal number or numeric string

Required: no

Purpose: Adds an absolute stop-loss stop price.

Validation:

- Must be greater than zero when included.
- Cannot be used at the same time as `stop_loss_ticks`.

`stopLossPrice` is also accepted as a camelCase alias.

### `profit_target_ticks`

Type: integer

Required: no

Purpose: Adds a profit target distance in ticks from the entry price.

Validation:

- Must be at least 1 when included.
- Cannot be used at the same time as `profit_target_price`.

Bracket parameters are intended for Tradovate leaders only in the FutuCopy UI.

### `profit_target_price`

Type: decimal number or numeric string

Required: no

Purpose: Adds an absolute profit target limit price.

Validation:

- Must be greater than zero when included.
- Cannot be used at the same time as `profit_target_ticks`.

`profitTargetPrice` is also accepted as a camelCase alias.

## Bracket TP/SL Copying And Suspended Orders

Stop loss and profit target fields create attached bracket/OSO child orders if the leader brokerage is Tradovate. Tradovate initially reports these attached child orders in `Suspended` status until the parent entry order fills.

`Suspended` is a Tradovate-specific order state and is not supported by other brokerages. FutuCopy is brokerage agnostic, so it does not copy `Suspended` TP/SL child orders to follower accounts. The leader entry order is still copied according to the user's copy configuration. After the leader entry fills and Tradovate transitions the attached TP/SL child orders from `Suspended` to `Live`/`Working`, those child orders become eligible to copy to followers.

This means a user may briefly see TP/SL orders on the Tradovate leader before they appear on followers. That is expected while the child orders are suspended. If the leader entry is canceled before the attached child orders become live, the child TP/SL orders may never be copied to followers.

## TradingView Placeholder Reference For FutuCopy

Recommended strategy placeholders:

- `{{strategy.order.action}}`: becomes `buy` or `sell`.
- `{{strategy.order.contracts}}`: becomes the number of contracts in the executed strategy order.
- `{{strategy.order.price}}`: becomes the price at which the TradingView strategy order was executed.
- `{{strategy.order.alert_message}}`: becomes the custom `alert_message` string produced by Pine Script order commands.

General placeholders that may be useful in custom Pine alert messages:

- `{{ticker}}`
- `{{close}}`
- `{{open}}`
- `{{high}}`
- `{{low}}`
- `{{time}}`

When answering questions about TradingView placeholders, confirm whether the user is using a strategy order-fill alert. Strategy placeholders do not populate in simple manual price alerts.

## Basic Market Order Example

Manual version:

```json
{
  "action": "buy",
  "contracts": 1,
  "leader_id": 1496,
  "order_type": "market"
}
```

Pine Script placeholder version:

```json
{
  "action": "{{strategy.order.action}}",
  "contracts": {{strategy.order.contracts}},
  "leader_id": 1496,
  "order_type": "market"
}
```

## Limit Order Example

Manual version:

```json
{
  "action": "buy",
  "contracts": 1,
  "leader_id": 1496,
  "order_type": "limit",
  "price": 7235
}
```

Pine Script placeholder version using strategy fill price:

```json
{
  "action": "{{strategy.order.action}}",
  "contracts": {{strategy.order.contracts}},
  "leader_id": 1496,
  "order_type": "limit",
  "price": {{strategy.order.price}}
}
```

## Stop Order Example

Manual version:

```json
{
  "action": "buy",
  "contracts": 1,
  "leader_id": 1496,
  "order_type": "stop",
  "price": 7235
}
```

Pine Script placeholder version using strategy fill price:

```json
{
  "action": "{{strategy.order.action}}",
  "contracts": {{strategy.order.contracts}},
  "leader_id": 1496,
  "order_type": "stop",
  "price": {{strategy.order.price}}
}
```

## Bracket Example With Tick-Based Stop Loss And Profit Target

```json
{
  "action": "{{strategy.order.action}}",
  "contracts": {{strategy.order.contracts}},
  "leader_id": 1496,
  "order_type": "market",
  "stop_loss_ticks": 40,
  "profit_target_ticks": 40
}
```

## Bracket Example With Absolute Stop Loss And Profit Target Prices

```json
{
  "action": "buy",
  "contracts": 1,
  "leader_id": 1496,
  "order_type": "market",
  "stop_loss_price": 7210.25,
  "profit_target_price": 7260.25
}
```

Do not include both tick-based and price-based versions for the same bracket side. For example, do not include both `stop_loss_ticks` and `stop_loss_price` in the same message.

## Flatten Examples

Flatten one leader:

```json
{
  "action": "flatten",
  "leader_id": 1496
}
```

Flatten all:

```json
{
  "action": "flatten_all"
}
```

## Simplest TradingView Strategy Test

Use this Pine Script to generate strategy order fills that populate `{{strategy.order.action}}` and `{{strategy.order.contracts}}`:

```pinescript
//@version=6
strategy("FutuCopy Placeholder Test", overlay=true, process_orders_on_close=true)

if bar_index % 2 == 0
    strategy.entry("Test Long", strategy.long, qty=1)
else
    strategy.close("Test Long")
```

TradingView alert setup:

1. Add the strategy to the chart.
2. Create an alert.
3. Choose the strategy as the alert condition.
4. Choose the order-fill alert option, such as "Order fills" or "Order fills and alert() function calls".
5. Add the FutuCopy webhook URL to the Webhook URL field.
6. Use this alert message:

```json
{
  "action": "{{strategy.order.action}}",
  "contracts": {{strategy.order.contracts}},
  "leader_id": 1496,
  "order_type": "market"
}
```

Use a valid `leader_id` from the user's FutuCopy Webhooks page.

## Using `strategy.order.alert_message` For Advanced Pine Values

If the user needs Pine-calculated values that are not available through TradingView placeholders, build the entire JSON message in Pine Script and send it through `alert_message`.

In the TradingView alert Message field, use only:

```text
{{strategy.order.alert_message}}
```

Then in Pine Script, pass a valid JSON string to an order command's `alert_message` parameter.

Conceptual example:

```pinescript
//@version=6
strategy("FutuCopy Custom Alert Message Example", overlay=true)

float myStopPrice = close + syminfo.mintick * 4
string msg = '{"action":"buy","contracts":1,"leader_id":1496,"order_type":"stop","price":' + str.tostring(myStopPrice, format.mintick) + '}'

if barstate.isconfirmed
    strategy.entry("Stop Long", strategy.long, qty=1, stop=myStopPrice, alert_message=msg)
```

The JSON string must remain valid after TradingView sends it.

## Response Shape

Successful and handled webhook responses use this shape:

```json
{
  "success": true,
  "message": "Webhook received and order submitted to brokerage. Check the Orders table for final order status.",
  "errorCode": null,
  "orderId": "optional",
  "timestamp": "UTC timestamp"
}
```

Some handled responses may have HTTP 200 but `success: false` when the request reached FutuCopy but the order or flatten operation could not be completed. Users should read the `message` and `errorCode`.

Validation and authentication errors use this shape:

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable error message",
    "details": null,
    "traceId": "request trace id",
    "timestamp": "UTC timestamp"
  }
}
```

## Common Error Codes

- `INVALID_REQUEST`: Missing or invalid fields, body too large, incompatible field combination.
- `UNAUTHORIZED`: Invalid token format or invalid token.
- `FORBIDDEN`: Token user is not allowed for the endpoint.
- `LEADER_NOT_FOUND`: `leader_id` does not belong to an eligible configured leader.
- `INVALID_ACTION`: `action` is not supported.
- `INVALID_OPERATION`: The requested operation is not supported in the current context.
- `FLATTEN_FAILED`: Flatten operation failed.
- `FLATTEN_NO_ACCOUNTS`: No accounts were available for flatten.
- `ROUTING_UNAVAILABLE`: FutuCopy could not route the request to the user's trading service.
- `RATE_LIMITED`: Too many webhook requests in a short time.
- `INTERNAL_ERROR`: Unexpected server-side error.

## Exact Validation Messages To Expect

These are common validation messages:

- `Invalid webhook token format.`
- `Invalid webhook token.`
- `Webhook token is not valid for this endpoint.`
- `Action must be 'buy', 'sell', 'flatten', or 'flatten_all'.`
- `leader_id is required.`
- `Action must be 'buy' or 'sell'.`
- `Contracts must be greater than zero.`
- `Order type must be 'market', 'limit', or 'stop'.`
- `Price is required and must be greater than zero for limit and stop orders.`
- `Price can only be used with limit and stop orders.`
- `Use either stop_loss_ticks or stop_loss_price, not both.`
- `Use either profit_target_ticks or profit_target_price, not both.`
- `stop_loss_price must be greater than zero.`
- `profit_target_price must be greater than zero.`
- `Trade copy leader with ID {leader_id} not found.`
- `Leader has no account assigned. Cannot flatten account-agnostic leaders.`
- `Leader has no account assigned. Cannot place orders on account-agnostic leaders.`
- `Webhook request body is too large.`
- `Too many webhook requests. Please retry shortly.`

## Troubleshooting Guide For AI Assistants

If placeholders arrive literally, such as `"{{strategy.order.action}}"`, the user probably tested with a manual alert or the wrong TradingView alert type. Tell them to create a strategy order-fill alert.

If `contracts` causes invalid JSON, check whether it was quoted or left blank. Recommended JSON is:

```json
"contracts": {{strategy.order.contracts}}
```

If a market order fails because of `price`, remove the `price` field. FutuCopy requires no `price` for market orders.

If a limit or stop order fails because of missing price, add `price`.

If `leader_id` fails, ask the user to open the FutuCopy Webhooks page and confirm the ID from the Configured Leaders table. The leader must have an assigned leader account.

If `stop_loss_ticks` and `stop_loss_price` are both present, remove one. The same rule applies to `profit_target_ticks` and `profit_target_price`.

If TP/SL orders appear on a Tradovate leader but not on followers immediately, check whether the attached TP/SL child orders are still in `Suspended` status. FutuCopy is brokerage agnostic and does not copy `Suspended` orders because that state is Tradovate-specific. Once the leader entry fills and the child orders transition to `Live`/`Working`, they become eligible to copy to followers.

If the webhook URL works from TradingView but not from another tool, that is expected. The public endpoint is intended for TradingView webhook delivery. Use the FutuCopy Webhooks page's built-in Test Webhook button for manual testing.

If the user changes Pine Script code after creating an alert, tell them to recreate the TradingView alert. TradingView alert instances keep a snapshot of the script and chart context at the time the alert is created.

If the user wants the actual current chart price rather than strategy fill price, clarify the goal:

- For executed strategy order price, use `{{strategy.order.price}}`.
- For current bar close in an alert message, use `{{close}}`.
- For a Pine-calculated order level, build the JSON in Pine and send it through `{{strategy.order.alert_message}}`.

## User-Facing Safety Warnings

Webhook tests can place real orders. A buy or sell webhook places an order on the selected leader account, and if copy trading is enabled, follower accounts may receive copied orders too.

Flatten webhooks close positions for the requested scope.

Users should test carefully with the smallest safe size and on the correct leader.

Users should rotate their webhook token if it is exposed.