TradingView alert message JSON: placeholders and payloads

Short answer: TradingView alert message JSON is the text you put in an alert's Message field, or build in Pine Script with alert() or alert_message, so that the webhook body is a JSON object. If the message is valid JSON, TradingView sends it with an application/json content type, otherwise as text/plain. Placeholders such as {{ticker}}, {{close}}, {{timenow}} and {{strategy.order.action}} are replaced with live values when the alert fires, so the template must remain valid JSON after substitution.

The alert message is the only data a TradingView webhook bot receives. TradingView's Help Center describes no way to add custom headers or sign the request, so everything the bridge needs, from symbol and side to an authentication secret and a unique alert ID, has to be in that text.

Below: the placeholders TradingView documents as of October 2026, per-order messages in Pine Script, a tested Python validator and common mistakes.

How does the alert message become the webhook body?

When an alert with a Webhook URL fires, TradingView replaces the placeholders and posts the resulting message as the body of an HTTP request.

• Content type. Valid JSON is sent as application/json; anything else, including JSON broken by an empty value, arrives as text/plain, which a bridge should treat as a failed alert.
• Length. The alert dialog's Message field takes up to 4,000 characters, messages built with Pine's alert() function or alert_message argument up to 40,960, and the same limits apply to the request body (as of October 2026).
• Source of the text. Most alerts use the dialog text; alert() calls build the message in code; strategy order-fill alerts use the dialog text, which can pull per-order text through {{strategy.order.alert_message}}.
• Snapshot. An alert keeps a copy of the script and inputs from its creation; recreate it after code changes.

TradingView's Terms of Use (opens in a new tab), read on 5 November 2026, describe alerts and webhooks as licensed for display use and prohibit using them for automated trading, including through third-party products or services. Read those terms and take legal advice before relying on this route; it is your agreement with TradingView.

TradingView placeholders for webhook JSON (as of October 2026)

TradingView's Help Center documents the following placeholders.

Strategy placeholders work only in strategy alerts. On an alert that fires before the bar closes, {{close}} is the latest price, not the final close, and {{strategy.order.price}} is a simulated fill, not your exchange price.

How to write a JSON template that survives substitution

Write the template so that it stays valid JSON whatever a placeholder turns into. A strategy alert template might look like this:

{
  "v": 1,
  "secret": "replace-with-a-long-random-string",
  "symbol": "{{ticker}}",
  "side": "{{strategy.order.action}}",
  "qty": "{{strategy.order.contracts}}",
  "ref_price": "{{close}}",
  "alert_id": "{{ticker}}-{{interval}}-{{strategy.order.id}}-{{time}}",
  "sent_at": "{{timenow}}"
}

Quoting every placeholder, numeric ones included, is the defensive choice: a missing or odd value still yields valid JSON, which the bridge rejects with a clear reason. TradingView documents placeholder prices as fixed-point numbers with a decimal point; parse them as decimals, not binary floats, then round to the exchange's tick and lot sizes.

alert() and alert_message in Pine Script strategies

Pine Script builds messages in code with alert() or with the alert_message argument of order commands.

• alert(message, freq) works in indicators and strategies, with alert.freq_once_per_bar (default), alert.freq_once_per_bar_close or alert.freq_all. In strategies, alert() calls run at bar close by default regardless of freq unless calc_on_every_tick is enabled. The user selects Any alert() function call when creating the alert.
• alert_message is an argument of strategy.entry(), strategy.exit(), strategy.order(), strategy.close() and strategy.close_all(). When the order fills, its text replaces {{strategy.order.alert_message}} in the dialog's Message field. Order-fill alerts trigger at the moment of execution.

A hypothetical strategy that attaches a small JSON object to each order (syntax illustration only, not compiled in TradingView and not a trading signal):

//@version=6
strategy("Hypothetical webhook payloads", overlay = true)
fast = ta.ema(close, 12)
slow = ta.ema(close, 26)
if ta.crossover(fast, slow)
    strategy.entry("Long", strategy.long,
         alert_message = '{"type":"entry","ref":"' + str.tostring(close, format.mintick) + '"}')
if ta.crossunder(fast, slow)
    strategy.close("Long", alert_message = '{"type":"exit"}')

The dialog's Message field can then nest the per-order text as an object:

{"v": 1, "secret": "replace-with-a-long-random-string", "symbol": "{{ticker}}",
 "side": "{{strategy.order.action}}", "qty": "{{strategy.order.contracts}}",
 "alert_id": "{{ticker}}-{{interval}}-{{strategy.order.id}}-{{time}}", "sent_at": "{{timenow}}",
 "order": {{strategy.order.alert_message}}}

Three documented rules matter here (as of October 2026):

• Placeholders cannot be used inside alert_message, and the documentation lists them only for alertcondition() and the dialog; build dynamic values in code with str.tostring() and variables such as syminfo.ticker.
• An order command without alert_message turns the placeholder into an empty string, so the nested template becomes invalid JSON and arrives as text/plain.
• str.tostring() returns the string NaN for an na value. NaN is not a valid JSON number under RFC 8259, and str.tostring(value, format.mintick) rounds prices to the symbol's tick size.

Designing a robust payload: version, secret and idempotency key

A robust payload is versioned, authenticated, unique and easy to validate.

A secret in the body is a shared password, not a signature: anyone who sees a message can replay it. Combine it with HTTPS, TradingView's source IP addresses, a timestamp window and a store of processed alert IDs. Exchange keys stay on the server with trade-only permissions, as described in API key security for trading bots.

Validating TradingView webhook JSON in Python

The validator below runs before anything reaches an exchange: it parses strictly, compares the secret in constant time, enforces an allowlist and types, and rejects stale messages. For a complete web service, see a tested webhook receiver in Python.

import hmac
import json
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation

SECRET = b"replace-with-a-long-random-string"   # never an exchange key or password
SYMBOLS = {"BTCUSDT", "ETHUSDT"}                # allowlist for this bot
VERSIONS = {1}

def reject_constant(name):                      # json.loads accepts NaN by default
    raise ValueError(f"non-standard JSON value {name}")

def validate(body, now, max_age_s=60):
    try:
        msg = json.loads(body, parse_constant=reject_constant)
    except RecursionError:                      # a body of thousands of opening brackets
        raise ValueError("JSON nested too deeply") from None
    if not isinstance(msg, dict):
        raise ValueError("message is not a JSON object")
    if not hmac.compare_digest(str(msg.get("secret", "")).encode(errors="replace"), SECRET):
        raise ValueError("bad secret")
    v, symbol = msg.get("v"), msg.get("symbol")
    if not isinstance(v, int) or v not in VERSIONS:
        raise ValueError("unknown schema version")
    if not isinstance(symbol, str) or symbol not in SYMBOLS:
        raise ValueError("symbol not allowed")
    if msg.get("side") not in ("buy", "sell"):
        raise ValueError("side must be buy or sell")
    try:
        qty = Decimal(str(msg.get("qty")))
    except InvalidOperation:
        raise ValueError("qty is not a number") from None
    if not qty.is_finite() or qty <= 0:
        raise ValueError("qty must be a positive number")
    sent = datetime.strptime(str(msg.get("sent_at")), "%Y-%m-%dT%H:%M:%SZ")
    age = (now - sent.replace(tzinfo=timezone.utc)).total_seconds()
    if not -5 <= age <= max_age_s:
        raise ValueError(f"alert is {age:.0f} s old")
    alert_id = msg.get("alert_id")
    if not isinstance(alert_id, str) or not alert_id:
        raise ValueError("missing alert_id")
    return alert_id, msg["side"], symbol, qty

good = ('{"v": 1, "secret": "replace-with-a-long-random-string", "symbol": "BTCUSDT", '
        '"side": "buy", "qty": "0.01", "ref_price": "67250.5", '
        '"alert_id": "BTCUSDT-60-Long-2026-10-24T14:00:00Z", "sent_at": "2026-10-24T14:00:03Z"}')
tests = {
    "good": good,
    "NaN qty": good.replace('"0.01"', "NaN"),
    "empty alert_message": '{"v": 1, "order": , "sent_at": "2026-10-24T14:00:03Z"}',
    "two minutes late": good.replace('14:00:03Z"}', '13:58:03Z"}'),
}
now = datetime(2026, 10, 24, 14, 0, 5, tzinfo=timezone.utc)   # hypothetical arrival time
for name, body in tests.items():
    try:
        print(f"{name}: accepted {validate(body, now)}")
    except ValueError as err:
        print(f"{name}: rejected ({err})")

Running it prints:

good: accepted ('BTCUSDT-60-Long-2026-10-24T14:00:00Z', 'buy', 'BTCUSDT', Decimal('0.01'))
NaN qty: rejected (non-standard JSON value NaN)
empty alert_message: rejected (Expecting value: line 1 column 19 (char 18))
two minutes late: rejected (alert is 122 s old)

Python's json module accepts NaN and Infinity by default, outside the JSON specification, so parse_constant rejects them. The secret is checked before any other field, and wrong types, such as a list as v or symbol, or a body nested too deeply, are rejected without an uncaught error. Decimal keeps 0.01 exact. The 60-second window passes resends, which come 5 seconds apart, to the deduplication step in the webhook bot guide, while refusing messages that arrive minutes late.

Common mistakes with TradingView alert JSON

Most broken automations trace back to a handful of template errors.

• Typographic quotes or a trailing comma pasted from a document editor, which silently turn the message into text/plain.
• Strategy placeholders in an indicator alert, where they do not work.
• Nesting {{strategy.order.alert_message}} while some order commands have no alert_message.
• Confusing {{time}} (bar open) with {{timenow}} (fire time), or assuming local time; both are UTC.
• Matching {{exchange}} exactly when delayed data adds _DL or _DLY.
• Treating {{close}} or {{strategy.order.price}} as the price you will get.

Templates, parsing rules and risk checks belong in the specification of a TradingView automation project, as in the order bridge scenario. A valid payload says nothing about whether the strategy works, and automated orders can lose money; verify the logic separately, for example with a Python re-implementation.

Frequently asked questions

Does TradingView send webhooks as JSON or plain text?

It depends on the message. If the alert message is valid JSON, TradingView sends it with an application/json content type; otherwise it uses text/plain, so a broken template still arrives, but as plain text.

Can I add custom headers or a signature to a TradingView webhook?

TradingView's Help Center describes no option for custom headers or signing; only the alert message is sent. Authenticate with a secret in the message, the published source IP addresses and, over HTTPS, TradingView's webhook certificate.

Why is {{strategy.order.alert_message}} empty?

The order command that filled had no alert_message argument, so Pine replaced the placeholder with an empty string, which can make a JSON template invalid. Strategy placeholders also work only in strategy alerts.

What time zone do {{time}} and {{timenow}} use?

Both are UTC, formatted like 2019-08-27T09:56:00Z. {{time}} is the bar's opening time and {{timenow}} the moment the alert fired, to the nearest second.

How long can a TradingView alert message be?

As of October 2026, 4,000 characters in the Message field of the alert dialog and 40,960 characters for messages built with alert() or alert_message; the same limits apply to the webhook body.

Sources

• TradingView Help Center: How to use a variable value in alert (placeholders) (opens in a new tab)
• TradingView Help Center: How to configure webhook alerts (opens in a new tab)
• TradingView Help Center: Alert name and message size limits (opens in a new tab)
• TradingView Help Center: Webhook authentication (opens in a new tab)
• TradingView Help Center: Webhook resubmission (opens in a new tab)
• TradingView Help Center: Strategy alerts (opens in a new tab)
• TradingView Pine Script v6 User Manual: Alerts (opens in a new tab)
• TradingView Pine Script v6 Reference Manual (alert, strategy.entry, str.tostring, format.mintick) (opens in a new tab)
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format (opens in a new tab)
• Python documentation: json (parse_constant, NaN handling) (opens in a new tab)
• Python documentation: hmac.compare_digest (opens in a new tab)
• Python documentation: decimal (opens in a new tab)
• TradingView: Terms of Use (read 5 November 2026) (opens in a new tab)

This guide is general information about software and markets, not investment, legal or tax advice. Automated trading can lose money, past or backtested performance does not guarantee future results, and the rules that apply depend on your jurisdiction and your exchange's terms. Sources, checks and corrections: see the editorial policy.