Signal Formatting

Overview#

PineHook accepts webhook signals in two interchangeable formats: CSV (plain text) and JSON. The platform auto-detects the format on each request, so you can choose whichever is easier to write in TradingView's alert editor. Every signal requires three core fields: a license key, a command, and (for most commands) a symbol, plus whatever parameters the command needs. Signals that fail validation are rejected immediately, with the reason returned to TradingView and recorded in the Signal Logs dashboard.

---

How It Works#

1. TradingView fires an alert and posts the payload to your webhook URL.
2. The platform detects the format: payloads that begin with { are parsed as JSON; all other payloads are parsed as CSV.
3. The three core fields (license key, command, and symbol) are extracted and validated first.
4. Additional parameters are parsed and validated. If any required parameter is missing, out of range, or conflicts with another, the signal is rejected at this step.
5. On rejection, the platform records the reason in Signal Logs (provided the license key was valid and extractable) and returns an HTTP 400 response to TradingView with the rejection reason in the body.
6. On success, the signal is queued and delivered to the connected EA. TradingView shows a green result on the alert's execution history.

---

Duplicate and Repeated Alerts#

TradingView re-sends a webhook when its first attempt is slow to respond or returns a server error, and those retries carry a byte-identical payload. To stop one alert from opening a position twice, the platform collapses identical repeats: if the exact same payload for the same license arrives again within a short window (about 12 seconds), it is treated as a duplicate — the original signal's result is returned, no second copy is queued, and the trade is not executed again.

• You do not need to worry about TradingView's automatic retries double-filling an order.
• A strategy that intentionally fires the very same command twice within ~12 seconds (identical symbol, side, size, and parameters) will see the second one collapsed into the first. If you genuinely want two identical entries that fast, vary something in the payload or space them more than ~12 seconds apart.
• The window is short by design, so normal trading — even many different signals per minute — is unaffected.

---

Signal Formats#

CSV#

CSV uses plain text with comma-separated fields on a single line.

Structure:

LICENSE_KEY,action,SYMBOL,param1=value1,param2=value2,...

Rules:

• The first three fields are positional and order-enforced: license key, then command, then symbol. Any other arrangement causes a field-order rejection.
• Parameters after the symbol are key=value pairs separated by commas. Their order after the symbol is flexible.
• Each field is trimmed of leading and trailing spaces before parsing.
• Commands and parameter keys are case-insensitive (BUY, buy, and Buy are treated identically).
• Symbols are automatically uppercased on receipt (eurusd becomes EURUSD).
• The payload must be a single line. Embedded newlines and tabs are not permitted.

Multi-symbol parameters in CSV:

Commands that accept a list of symbols (eaoffexcept, eaonexcept) separate values with semicolons within the parameter value:

LICENSE_KEY,eaoffexcept=EURUSD;GBPUSD;USDJPY

Compact multi-target TP/SL in CSV:

Multi-TP and multi-SL targets support a compact shorthand as the value of tp_pips or sl_pips. Each segment follows the pattern pips:close_percentage, separated by semicolons. The last segment may omit the percentage; the platform assigns the remainder to reach 100%. A malformed compact string (a non-numeric segment, pips ≤ 0, a close percentage over 100, or a trailing remainder that works out to 0%) is rejected with an error — it is no longer silently dropped. A complete single level such as tp_pips=30:100 (one TP closing 100%) is accepted.

LICENSE_KEY,buy,EURUSD,size_lots=0.1,tp_pips=30:50;60:30;100

This sets three targets: 30 pips (close 50%), 60 pips (close 30%), 100 pips (close remaining 20%). See the multi-target TP/SL article for full details.

---

JSON#

JSON uses a standard object payload. Field order is irrelevant; the platform looks up fields by key name.

Structure:

{"license": "LICENSE_KEY", "action": "buy", "symbol": "EURUSD", "size_lots": 0.1}

Rules:

• Field names for recognized keys are case-insensitive and normalized to lowercase ("license", "action", "symbol"); lowercase is recommended.
• Parameter values follow standard JSON typing: strings, numbers, and arrays where documented.
• Symbols are automatically uppercased on receipt, same as CSV.
• Any valid JSON is accepted: formatted (with whitespace) or minified (no whitespace).

JSON-only features:

• Multi-target TP/SL can use the tp_targets and sl_targets keys, which accept arrays of objects. Each object specifies one target level using pips, price, or pct plus close_pct or close_lots. The compact string syntax also works in JSON by passing it as a string value for tp_pips or sl_pips.
• Multi-symbol commands (eaoffexcept, eaonexcept) accept a symbols key that can be a JSON array or a comma/semicolon-separated string.

---

Minified JSON#

Minified JSON (no whitespace between fields) is fully supported and treated identically to formatted JSON. TradingView's alert editor often produces minified JSON naturally:

{"license":"ABCD-EF01-2345-6789","action":"buy","symbol":"EURUSD","size_lots":0.1,"sl_pips":50,"tp_pips":100}

No special handling or configuration is needed for minified payloads.

---

Core Required Fields#

License Key#

Identifies your license. Every signal must include it.

• CSV position: First field (position 1).
• JSON key: "license"
• Required format: XXXX-XXXX-XXXX-XXXX: four groups of four hexadecimal characters (0-9, A-F), separated by hyphens. Case-insensitive on input.
• Error on invalid format: Invalid license key format - expected XXXX-XXXX-XXXX-XXXX (hex characters only)

Critical: If the license key is missing or fails format validation, no Rejected Signals row is created. The rejection is still returned to TradingView, but you will not see it in Signal Logs. Always confirm the key is present and correctly formatted before checking for a Rejected Signals entry.

---

Command (Action)#

Tells the EA what action to perform. Commands are case-insensitive.

• CSV position: Second field (position 2).
• JSON key: "action"
• Error if missing: Missing 'action' - signals require: license, action, symbol
• Error if unrecognized (close match found): Unknown command '{command}' - did you mean '{suggestion}'?
• Error if unrecognized (no close match): Unknown command '{command}' - valid commands include: buy, sell, closelong, closeshort, closeall, etc.
• Deprecated name: canceldelay was renamed to clearqueue. Sending the old name returns an error pointing to clearqueue; it does not silently execute.

---

Symbol#

The trading instrument the command applies to.

• CSV position: Third field (position 3).
• JSON key: "symbol"
• Required format: 1 to 20 uppercase alphanumeric characters (A-Z, 0-9). No slashes, dashes, dots, spaces, or other special characters. Automatically uppercased on receipt.
• Error on invalid format: Invalid symbol '{symbol}'. Symbols must be 1-20 uppercase alphanumeric characters (A-Z, 0-9).
• Error if missing (when required): Missing 'symbol' - signals require: license, action, symbol

Commands that do not require a symbol in the standard third-field position: eaon, eaoff, eaoffexcept, eaonexcept, closeall, closecancelall, cancelall, clearqueue, closealleaoff, closecancelalleaoff, closeallprofit, closeallloss

eaoffexcept and eaonexcept still require at least one symbol in the parameter value (e.g., eaoffexcept=EURUSD;GBPUSD). Sending either with no symbols is rejected and surfaces in Signal Logs → Rejected Signals with reason "missing_symbol". Use eaoff,ALL or eaon,ALL for the all-symbols cases.

Symbol filter list size limit: the symbol filter (in either blacklist or whitelist mode) is capped at 100 symbols. Any EA control command (eaon, eaoff, eaoffexcept, eaonexcept, or an inline eaon= / eaoff= parameter on a trade command) that would leave the filter with more than 100 entries is rejected with block_reason="filter_list_too_long". The rejection message reports the would-be size and suggests switching to the inverse filter mode (e.g., "you're blacklisting 100+ symbols, consider a whitelist of just the few you want to allow"). The filter is not modified when this happens.

---

Commands Reference#

---

Parameters Reference#

Position Sizing#

Required for all trade-opening commands (buy, sell, and all pending order commands). Use exactly one.

• Using both in the same signal: rejected with Conflicting position sizing parameters: size_lots, size_pct. Use either size_lots (fixed volume) or size_pct (risk-based), not both.
• Omitting both on a trade-opening command: rejected with Position sizing is required. Specify size_lots (fixed volume, e.g. size_lots=0.1) or size_pct (risk-based, e.g. size_pct=1.5)...
• size_pct without a stop loss: rejected with size_pct requires a stop loss to calculate position size...; add sl_pips, sl_price, or sl_pct.

---

Stop Loss#

Optional for most commands, but required when size_pct is used. Use at most one.

Using more than one format in the same signal: Conflicting stop loss parameters: {params}. Use only one of: sl_pips, sl_price, or sl_pct.

---

Take Profit#

Optional. Use at most one.

Using more than one format: Conflicting take profit parameters: {params}. Use only one of: tp_pips, tp_price, or tp_pct.

---

Multi-Target TP/SL (Up to 10 Levels)#

Splits the position across multiple take-profit or stop-loss price targets. See the multi-target TP/SL article for full syntax documentation.

Key constraints:

• Levels must be numbered sequentially from 1 with no gaps (tp1, tp2, tp3, etc.). Skipping from tp1 to tp3 without a tp2 is rejected.
• Close percentages across all levels must sum to exactly 100%.
• Cannot mix _close (percentage) and _lots (fixed volume) on the same side.
• Maximum of 10 targets per side.

Available input modes:

• Individual parameters: tp1_pips=30, tp1_close=50, tp2_pips=60, tp2_close=30, etc.
• Compact string (CSV or JSON string value): tp_pips=30:50;60:30;100
• JSON array (JSON only): "tp_targets": [\{"pips": 30, "close_pct": 50\}, ...]

---

Pending Order Entry Price#

The platform also validates that SL and TP prices are on the correct side of the entry price when absolute prices are used:

• Buy orders: TP must be above entry; SL must be below entry.
• Sell orders: TP must be below entry; SL must be above entry.

---

Trailing Stop#

Use exactly one distance mode. These parameters are also valid on trail commands issued separately after a position opens. See the trailing stop and breakeven article for full details.

Trigger modes are mutually exclusive: use at most one of trail_trigger, trail_trigger_pct, trail_trigger_price.

The pips-based trailing fields (distance_pips, trail_step, trail_trigger) reject a finite-but-absurd value above roughly 1,000,000 pips; their _pct/_atr siblings were already bounded. An absurd value placed the trailing stop so far away it never engaged, leaving you with a silently dead trailing stop you believed was active. A legitimately wide trailing distance is unaffected.

---

Auto-Breakeven#

Use exactly one trigger mode and exactly one offset mode. See the trailing stop and breakeven article.

Trigger modes are mutually exclusive; offset modes are mutually exclusive.

---

Trade Filtering#

These parameters narrow which positions or orders a command affects.

---

Spread and Slippage Protection#

---

Timing and Scheduling#

---

Other Parameters#

---

Payload Size Limit#

All signals must be 2,048 bytes or smaller. Signals exceeding this size return HTTP 413 (payload too large). No Rejected Signals row is created for oversized payloads; the rejection appears only in the TradingView alert response. The most common cause is an unusually long comment value.

---

Error Messages and Meanings#

Group A: Validation Rejections (HTTP 400)#

Surface: Signal Logs → Rejected Signals tab AND TradingView alert execution history.

A Rejected Signals row is only created when the platform can extract a valid license key from the payload. If the key is absent or fails format validation, no row appears in Signal Logs. The rejection is still returned to TradingView. Very long rejection messages may be shortened.

---

Group B: Plan and Rate Limit Rejections#

Surface: TradingView alert response: HTTP 402 for the plan gates (delay requires a paid plan, expiry cap exceeded); HTTP 429 for the queue-full and rate-limit rejections. Rate-limited signals (HTTP 429) are recorded: they appear in Signal Logs as a Blocked row and in Rejected Signals, with reason rate_limited (per-minute) or rate_limited_daily (per-day).

---

Group C: Payload Size (HTTP 413)#

Surface: TradingView alert response only. No Rejected Signals row is created.

---

Group D: Signal Authentication (HTTP 200, status blocked)#

Surface: Signal Logs → Rejected Signals tab AND the TradingView alert response.

Signal-authentication failures are not validation rejections. The request is well-formed and the license key is valid, so the platform returns HTTP 200 with a body of {"status": "blocked", "reason": ..., "message": ...} rather than a 4xx error. The signal is recorded as blocked and surfaces in the Rejected Signals tab. (An unknown or invalid license key is different: that is an HTTP 401, not a signal-auth block.)

---

Where to look#

---

Plan and Tier Differences#

When a Trial period ends with no paid plan active, trade-opening signals are received but not executed. Close and cancel commands remain operational regardless of plan state.

---

Known Edge Cases and Gotchas#

• CSV third-field ambiguity: If the third comma-separated value contains an = character, the parser treats it as a key=value parameter rather than the symbol. Always place the symbol as a plain value with no = sign, and put all parameters after it.

• Automatic symbol uppercasing: Symbols are silently uppercased on receipt. eurusd and EURUSD produce identical results. This is by design but can confuse you if you compare your alert text against the uppercase value you see in Signal Logs.

• canceldelay is deprecated and does not execute: Sending this old command name returns an error pointing to clearqueue. It does not silently run the equivalent action.

• size_pct requires a stop loss: Without sl_pips, sl_price, or sl_pct in the same signal, the signal is rejected. The EA needs the SL distance to compute position size from a risk percentage.

• sl_price=0 and tp_price=0 are invalid: Zero is not accepted as a price value. Omit the field to open a position without a stop loss or take profit.

• sl_pips/tp_pips have an upper bound: A pip distance above roughly 1,000,000 is rejected with HTTP 400 (sl_pips is implausibly large …), mirroring the size_lots ceiling. This catches an absurd typo such as sl_pips=100000 when you meant 100 — on a SELL that places the stop so far away it never triggers, leaving an effectively naked position you believe is protected. A legitimately wide stop (well under 1,000,000 pips) is unaffected.

• Compact TP/SL must be valid or the signal is rejected (HTTP 400): The close percentages must sum to exactly 100% (an optional trailing bare-pips segment supplies the remainder). A malformed compact string — non-numeric segment, pips ≤ 0, a close percentage above 100, or a trailing remainder that resolves to 0% because earlier segments already total 100 (e.g. 30:50;60:50;100) — is now rejected with a clear error, not silently discarded. Previously such a string opened a position with no targets and no error message; that footgun is closed. A complete single level like tp_pips=30:100 is accepted.

• Multi-TP numbering must be sequential with no gaps: Specifying TP1 and TP3 without TP2 is rejected. Always number from 1 upward with no skipped levels.

• A single TP/SL cannot coexist with a multi-TP/SL ladder: Sending both a single tp_pips/tp_price/tp_pct and a multi-TP ladder (tp1_*…tp10_*) in one signal is rejected; use one or the other (the same applies to the SL side).

• Target indices above 10 are rejected: tp11_*, sl12_*, and higher fail with an error rather than being silently ignored. The maximum is 10 levels per side.

• Per-target close volumes and distances must be positive, finite, and sane: A tpN_lots/slN_lots (or JSON close_lots) that is negative, zero, NaN, Infinity, or implausibly large (a close volume far above any real position, or an absurd pips/price distance) is rejected at the server before it reaches the EA. In the JSON tp_targets/sl_targets array, a level-distance pct of 0 is also rejected, and a malformed element (a non-object, or a non-numeric value) rejects the whole signal — it no longer silently drops just that level.

• modify validates per-level format conflicts too: Setting two formats on the same level (e.g. modify,…,tp1_pips=50,tp1_price=…) is rejected on modify, the same as on entry.

• modify re-validates new levels against the broker freeze zone: A modify that moves a multi-TP/SL level inside the broker's minimum-stop distance (or already past current market) is skipped with a warning instead of being applied — otherwise the EA's tick-by-tick manager would fire it as an instant, unintended partial close. Move the level further from market and resend.

• Unrecognized parameters cause rejection even on market-order commands: A typo such as sl_pip instead of sl_pips causes the signal to fail with HTTP 400. Trade management commands (trail, breakeven, modify, etc.) are even stricter: they reject any parameter name they do not recognize, including parameters that are valid on other command types.

• Non-ASCII digits in numeric fields are rejected: Unicode fullwidth numerals (used in some Asian character sets) and other non-ASCII digit substitutes cause an explicit error. Use standard ASCII digits only.

• Multi-symbol syntax differs between CSV and JSON: In CSV, list symbols semicolon-separated inside the parameter value (e.g., eaoffexcept=EURUSD;GBPUSD). In JSON, use the symbols key with an array or comma/semicolon-separated string. The eaon and eaoff parameters in JSON accept only one symbol; use eaonexcept or eaoffexcept for multiple symbols.

• Payload limit is enforced at the gateway: Signals over 2,048 bytes return HTTP 413 and do not create a Rejected Signals row. The comment field is the most frequent cause of oversized payloads.

• trail_atr_timeframe is rejected on unrecognized values: A misspelled or unsupported timeframe value (e.g., 1H instead of H1) is rejected with HTTP 400 and recorded in Signal Logs -> Rejected Signals, rather than silently falling back to a default. Valid values are: M1, M5, M15, M30, H1, H4, D1, W1, MN1.

• auth is position-independent in CSV: The auth parameter can appear anywhere in the parameter list (before or after other parameters) and is always extracted by key name, not by position.

• Rate-limited signals are recorded: An HTTP 429 (per-minute or per-day cap) writes a Blocked row in Signal Logs and a row in Rejected Signals, with reason rate_limited or rate_limited_daily. If you're missing signals during a burst, look for these Blocked/Rejected rows to confirm you're hitting your plan's frequency limit. (Close and cancel commands are exempt from the caps.)

---

Frequently Asked Questions#

Q: Do I have to use JSON, or can I use CSV? A: Either format works for any command. Both CSV and JSON are fully supported everywhere. Choose whichever is easier to write in TradingView's alert message editor.

Q: Does field order matter in JSON? A: No. JSON field order is irrelevant; the platform looks up fields by key name. Field order only matters in CSV, where the first three values must appear as license key, then command, then symbol.

Q: My symbol includes a slash (like EUR/USD). Why is it rejected? A: Symbols must contain only letters (A-Z) and digits (0-9), with no separators. Use EURUSD instead of EUR/USD. Check the exact symbol name in the MT5 Market Watch window; brokers sometimes use suffixes such as EURUSDm or EURUSD.r.

Q: Can I include both size_lots and size_pct in the same signal? A: No. They are mutually exclusive. Use one or the other. A signal containing both is rejected.

Q: I sent a signal and nothing appeared in Rejected Signals. What happened? A: Rejected Signals rows are only created when the platform can extract a valid, correctly formatted license key from the payload. If the key is missing or malformed, no row appears. Rate-limited rejections (HTTP 429) also do not create rows. Check the TradingView alert response for the HTTP status code and body to determine what happened.

Q: What is the difference between tp_pips and tp1_pips? A: tp_pips sets a single take profit target for the whole position. tp1_pips is the first level of a multi-target take profit, where the position is split across multiple price levels. Use tp1_pips, tp2_pips, etc. only when splitting the position; for a single target, use tp_pips.

Q: Why is my delay parameter rejected with "requires a paid plan"? A: The delay parameter is not available on Trial accounts. Upgrade to a Standard, Pro, or Premium plan to queue signals for delayed execution, or remove the delay parameter from the alert.

Q: Can I use minified JSON in TradingView's alert body? A: Yes, fully supported. Minified JSON and formatted JSON are handled identically. TradingView's alert editor often produces minified payloads naturally.

Q: What does the rejection message "did you mean '{suggestion}'?" mean? A: The platform detected that a parameter name in the signal closely resembles a known parameter but is not an exact match, usually a typo. Replace the parameter name with the suggestion provided in the rejection message.

Q: My pending order signal is rejected even though I included all the fields I think are required. What am I missing? A: Three common causes: (1) the price parameter is missing; every pending order command requires an entry price; (2) a TP or SL price is on the wrong side of the entry (TP must be above entry for buy orders, below for sell orders; SL is the reverse); (3) sl_price or tp_price is set to 0, which is not a valid price. Check each against the rejection reason shown in the Rejected Signals tab.