Chapter 1: Core Concepts

1.1 What is WebhookTrade?

WebhookTrade is a specialized service that functions as a robust and efficient bridge between your TradingView account and your brokerage accounts. Its primary purpose is to receive trading alerts generated by your strategies in TradingView and translate them into executable trade commands that are sent to your connected broker, such as MetaTrader (MT4/MT5) or Capital.com.

1.2 The Challenge of Trading Automation

Automating trades from TradingView, especially to the world's most popular platform, MetaTrader, has traditionally been a complex and technically demanding process. It required traders to:

• Rent and maintain a Virtual Private Server (VPS) to ensure 24/7 uptime.
• Install and configure a MetaTrader terminal on that server.
• Find, purchase, and correctly set up a third-party Expert Advisor (EA) to interpret incoming signals.
• Manage potential downtime, internet issues, software crashes, and security updates.

This technical overhead creates a significant barrier for many traders who simply want to execute their well-defined strategies automatically.

1.3 The WebhookTrade Solution

WebhookTrade is designed to completely remove these technical barriers, providing a streamlined path to automation.

• For MetaTrader Users: We provide a fully managed, cloud-based service, eliminating the need for a VPS on your side. Instead of running your computer 24/7 or managing your own server, we handle the infrastructure for you. You simply provide your account details through our secure platform, and we establish a persistent connection for your account. This completely removes any need for software installation or EA configuration on your end.
• For API Broker Users: For brokers like Capital.com, we provide a unified and simplified interface to securely connect your accounts, bypassing the need for you to write or manage any code for API integration.
• For All Users: We provide a suite of tools to help you construct, test, and monitor your trading alerts, ensuring a smooth and reliable automation experience.

Chapter 2: Quick Start Guide

This guide provides the essential steps to configure your first automated trade.

1. Register and Log In: Create your account at WebhookTrade.com.
2. Connect Your Broker: Navigate to the "Connect to a broker or MetaTrader" page. Select your platform (e.g., MetaTrader) and provide your account details. Upon a successful connection, the system will generate your unique WebhookTrade API Key.
3. Generate the Alert Message: Go to the "Set TradingView Alerts" page. Use the JSON Generator to build the command for your alert. Your `username` and `api_key` will be automatically included.
4. Prepare Your Alert in TradingView:
   • In TradingView, select the chart, strategy, and timeframe you wish to automate.
   • Click the "Add alert" button. In the alert configuration window, ensure your strategy is selected as the "Condition".
   • Go to the "Message" box, delete all existing content, and paste the JSON message you generated in WebhookTrade.
5. Configure the Notification Method: In the same TradingView alert window, go to the "Notifications" tab and choose one of these two methods:
   • Webhook URL (Recommended): Check this box. Copy the URL from the WebhookTrade "Set TradingView Alerts" page and paste it here. This method is available on all paid TradingView plans.
   • Send plain text: Check this box. Copy your unique, personalized email address from the WebhookTrade "Set TradingView Alerts" page and paste it here. This method works with any TradingView plan, including the free one. You will need to verify the email once by entering a code that we forward to your personal inbox.
6. Activate: Save the alert in TradingView. The system is now live. The next time your strategy triggers an alert, the trade will be executed, and the result will be logged in your WebhookTrade Dashboard.

Chapter 3: Platform Guide

This chapter provides a detailed walkthrough of each page within your WebhookTrade account.

3.1 The Dashboard (`/account/dashboard`)

The Dashboard is your central monitoring hub. It displays a comprehensive, real-time log of every signal received by our system for your account.

• Purpose: To provide a transparent and detailed record of all trading activity, allowing you to track performance, verify executions, and diagnose any potential issues with your alerts.
• Key Elements: The main feature is the Signal Log Table, which details the Symbol, Action, Size, SL/TP levels, Broker, Account Type, Source (webhook or email), execution Status, a detailed Summary from the broker (including error messages or ticket numbers), and the Date of the event. Powerful filtering tools at the top of the table allow you to narrow down the results by any of these criteria.

3.2 Broker Connections

The Connect Page (`/account/connect`) is the gateway to linking your brokerage accounts. From here, you will choose your desired integration type.

3.2.1 MetaTrader (MT4/MT5) (`/account/setmetatrader`)

This page facilitates our signature "done-for-you" MetaTrader integration.

• Purpose: To securely collect your MT4/MT5 account information, which our system uses to provision your dedicated, managed trading environment on our servers.
• Process: You will be prompted for your Platform (MT4/MT5), Login Number, Master Password, and the exact Server name provided by your broker. Our automated system then connect your account on our platform. This process typically takes 1-2 minutes. Upon completion, your connection status is confirmed, and your WebhookTrade API Key is displayed.

3.2.2 Capital.com (API) (`/account/setcapital`)

This page is for establishing a direct API connection with Capital.com.

• Purpose: To link your Capital.com account using their provided API keys, allowing for direct trade execution.
• Process: You will enter the API Key and API Key Password that you generate from within your Capital.com account settings. Once saved and validated, your WebhookTrade API Key will be displayed.

3.3 Set TradingView Alerts Page (`/account/jsonmaker`)

This is your primary workspace for constructing and verifying your alert commands.

• Purpose: To provide all the necessary tools and information for correctly configuring your TradingView alerts.
• Key Sections:
  1. JSON Generator: An interactive form that builds a syntactically correct JSON message as you input your trade parameters. This is the recommended method for creating your messages to prevent errors.
  2. Alert Sending Methods: This section provides the two methods for sending alerts from TradingView, giving you the flexibility to choose based on your TradingView plan.
  3. Alert Simulator: A crucial testing tool. You can paste a complete JSON message and click "Test Alert" to send a live trade to your connected account immediately. This allows you to verify your syntax and connection without waiting for a strategy to trigger.
     Caution

     Trades sent from the simulator are real and will be executed on your connected account. It is strongly recommended to use a DEMO account for initial tests.

3.4 Telegram Notifications (`/account/notificationstelegram`)

This feature allows you to receive real-time execution status updates on your mobile device via Telegram.

• Purpose: To stay informed about the outcome of every trade without needing to check the dashboard.
• Process: The page provides clear, step-by-step instructions on how to create your own Telegram Bot using @BotFather to get a Bot Token, and how to find your personal Chat ID using @userinfobot. You must then enter both the Bot Token and the Chat ID into the provided fields on this page and save them. Once configured, our system will be able to send a message to your bot every time a trade is successfully executed or fails.

3.5 Subscription Page (`/account/plan`)

This page is for managing your access to WebhookTrade services.

• Purpose: To view your trial status, subscribe to a plan, and manage your billing.
• Features: You can see your active plan, view the next billing date, and access our secure billing portal via the "Manage Subscription" button to update payment details or cancel your service.

3.6 Account Settings & Support

• Account Settings (`/account/user_settings`): A straightforward page to update your name and change your WebhookTrade account password.
• Support (`/account/support`): Your portal for getting help, including access to this documentation, FAQs, and methods for contacting our support team.

Chapter 4: Alert Message Specification

The JSON (JavaScript Object Notation) message is the core of your command. A precise understanding of its structure and parameters is key to leveraging the full power of WebhookTrade.

4.1 Basic Structure

Every alert must be a valid JSON object. The basic structure for a WebhookTrade alert is as follows:

{
  "username": "your_username",
  "api_key": "your_api_key",
  "broker": "metatrader",
  "symbol": "EURUSD",
  "action": "buy",
  "size": 0.1,
  ...
}

4.2 Parameter Reference

The following table details all available parameters.

4.3 In-Depth: `action`

The action parameter determines the operation to be performed. The following values are supported:

• "buy": Opens a new long position. Requires the size parameter.
• "sell": Opens a new short position. Requires the size parameter.
• "close_buy": Closes all open long positions for the specified symbol. The size parameter is ignored.
• "close_sell": Closes all open short positions for the specified symbol. The size parameter is ignored.
• "close_all": Closes all open positions (both long and short) for the specified symbol. The size parameter is ignored.

4.4 In-Depth: `size`

The size parameter specifies the volume of your trade and is interpreted differently by each platform.

• For MetaTrader: The size corresponds to Lots. A size of 1.0 on EURUSD is 1 standard lot (100,000 units). The minimum lot size for MetaTrader is 0.01; lower quantities will result in a size error. Only two decimal places will be considered. You should consult your broker's specifications to understand the contract size for each lot on different instruments (e.g., forex, indices, commodities).
• For Capital.com: The size corresponds to the number of contracts or units as defined by Capital.com for that specific instrument.

4.5 In-Depth: Stop Loss & Take Profit

You can define your exit points using two distinct methods. The system prioritizes distance-based stops if both types are provided in the same alert.

• Absolute Price Level: Use the take_profit and stop_loss parameters to specify the exact price at which to exit the trade.
• Distance from Entry: Use the tp_distance and sl_distance parameters to specify an exit point relative to the order's execution price.

Trailing Stops

To use a trailing stop, you must set "trailing_stop": true and provide the trail distance using the sl_distance parameter. The distance follows the same rules as above (Points for MetaTrader, Price Distance for Capital.com).

4.6 In-Depth: `execution_mode` (MetaTrader Only)

This powerful, optional parameter for MetaTrader alerts allows you to control how new orders interact with existing positions for the same symbol.

Supported Values:

• "mt_native": This is the default behavior if the execution_mode field is omitted from your JSON. The order is sent to MetaTrader as-is, and your terminal will behave according to its native configuration (usually hedging).
• "close_opposite": This activates our smart netting logic. It is designed to replicate the behavior of a netting account, where a new opposing order cancels out an existing one instead of opening a new position in the opposite direction. The process is as follows:
  1. When a new order is received (e.g., a BUY of 1.0 lot), the system first identifies any open SELL positions for the same symbol.
  2. It then closes the oldest opposing positions first.
  3. It continues closing positions until the volume of the new order is fully accounted for.
  4. Scenario A (New order is LARGER): If a new BUY 1.0 lot arrives and an existing SELL of 0.3 lots is open, the system will close the 0.3 lot SELL completely and then open a new BUY order for the remaining difference of 0.7 lots.
  5. Scenario B (New order is SMALLER or EQUAL): The system closes the oldest opposing positions completely until their total closed volume meets or exceeds the new order's volume. No new order is opened in this case.
     • Example: A new BUY 0.5 lot arrives. There is one existing SELL position of 1.0 lot.
     • Result: The system closes the entire 1.0 lot SELL position. Since the closed volume (1.0) is greater than the new order's volume (0.5), the process is complete. The final result is no open positions.

4.7 Using Dynamic Variables (Placeholders)

To create fully automated strategies, you can use TradingView's built-in placeholders, also known as dynamic variables, in your JSON message. These are special text snippets enclosed in double curly braces, like {{ticker}}. When an alert triggers, TradingView's system is designed to replace these placeholders with the relevant real-time values from your strategy or chart before sending the final message to WebhookTrade.

Commonly, for many standard strategies, you do not need to modify any Pine Script code for the most basic placeholders to work. TradingView is designed to handle their replacement automatically when you create an alert from a strategy script.

The most common placeholders include:

• {{ticker}}: The symbol of the chart the alert is on.
• {{strategy.order.action}}: The action (buy or sell) from a strategy order.
• {{strategy.order.contracts}}: The position size from a strategy order.

Beyond these standard variables, it is also possible to send dynamic values for other parameters, such as tp_distance or sl_distance, based on calculations within your strategy. However, it is crucial to understand that for all placeholders, both common and custom, the replacement is a function handled entirely by TradingView. WebhookTrade only accepts final, real values (like "buy" or 0.5). If a placeholder is not correctly replaced by TradingView, our system will receive the literal placeholder string (e.g., "action": "{{strategy.order.action}}"), which is not a valid command and will cause the trade to fail. Therefore, you must ensure that your Pine Script strategy and alert configuration are working correctly to replace these variables with actual values before the alert is sent.

In cases where a placeholder is not being replaced, or for sending custom values like dynamic stops, you will likely need to use the alert() function directly within your Pine Script code. This involves defining your variables in the script and then constructing the full JSON message as a string to be passed to the alert() function. The specifics of this implementation can vary depending on the strategy's code. For detailed guidance on how to use the alert() function and manage dynamic variables in Pine Script, please refer to the official Pine Script documentation.

4.8 JSON Examples

Example 1: Hybrid Alert (Dynamic Action, Fixed Parameters)

This common setup uses a fixed symbol, size, and stop levels, but allows the strategy to determine whether to buy or sell.

{
  "username": "mytrader123",
  "api_key": "YOUR_API_KEY",
  "broker": "metatrader",
  "symbol": "EURUSD",
  "action": "{{strategy.order.action}}",
  "size": "0.1",
  "tp_distance": "400",
  "sl_distance": "200",
  "execution_mode": "close_opposite"
}

Example 2: Comprehensive MetaTrader Strategy Alert

This example uses TradingView's dynamic variables for a fully automated strategy.

{
  "username": "mytrader123",
  "api_key": "YOUR_API_KEY",
  "broker": "metatrader",
  "symbol": "{{ticker}}",
  "action": "{{strategy.order.action}}",
  "size": "{{strategy.order.contracts}}",
  "tp_distance": "400",
  "sl_distance": "200",
  "execution_mode": "close_opposite"
}

Example 3: Capital.com Market Sell with Fixed Price Stops

{
  "username": "mytrader123",
  "api_key": "YOUR_API_KEY",
  "broker": "capital.com",
  "account_type": "demo",
  "symbol": "US30",
  "action": "sell",
  "size": "1",
  "take_profit": "39000",
  "stop_loss": "39500"
}

Example 4: MetaTrader Trailing Stop

{
  "username": "mytrader123",
  "api_key": "YOUR_API_KEY",
  "broker": "metatrader",
  "symbol": "XAUUSD",
  "action": "buy",
  "size": "0.05",
  "trailing_stop": true,
  "sl_distance": "1500"
}

Chapter 5: FAQ & Troubleshooting

What should I do first to start automating?

Once you have the TradingView strategy that you want to automate, the fastest way to get started is to follow our Quick Start Guide. The essential steps are: 1) Register at WebhookTrade, 2) Connect your broker account, 3) Use our JSON Generator to create your alert message, and 4) Paste that message into a new alert in TradingView, pointing it to our system via Webhook URL or email.

For the MetaTrader connection, do I need a VPS or to install an EA?

No. This is a core benefit of our service. You do not need to rent a Virtual Private Server (VPS), keep your computer running, or install any Expert Advisor (EA) software. WebhookTrade provides a fully managed, cloud-based service that handles the connection to your MetaTrader account 24/7.

Do I need to pay for a TradingView subscription?

Not necessarily. We offer two ways to send alerts from TradingView:

• Webhook URL: This method is faster and recommended, but it requires any paid TradingView plan (Pro, Pro+, or Premium).
• Send Plain Text: This method works with any TradingView plan, including the free one. You simply send the alert to your unique WebhookTrade email address.

Is it safe to provide my MetaTrader / Capital.com API details?

Yes. We prioritize your security. Sensitive information like passwords and API keys are encrypted before being stored.

Can I manage multiple MetaTrader accounts with one WebhookTrade account?

A single WebhookTrade account is designed to connect to one MetaTrader account. If you need to manage multiple MetaTrader accounts, you must create a separate WebhookTrade account for each one.

However, it is possible to combine different connection types. A single WebhookTrade account can simultaneously support:

• One (1) MetaTrader (MT4 or MT5) connection.
• And one (1) API-based broker connection (currently Capital.com).

This setup allows you to automate trades on two different platforms using a single WebhookTrade account and subscription.

I created an alert in TradingView, but I don't see it on the WebhookTrade dashboard.

If a signal doesn't appear in your dashboard, it likely means our system never received it. The most common reasons are:

• Incorrect JSON Format: The message in your TradingView alert is not valid JSON. Even a missing comma or quote will cause it to fail. Always use the JSON Generator on our "Set TradingView Alerts" page to create your message. An incorrect username will also cause this.
• Strategy Not Firing: Your strategy's conditions may not have been met, so TradingView never triggered the alert. Check the "Logs" tab (next to the "Alerts" tab) in your TradingView panel to confirm if an alert was actually sent.
• Incorrect Notification Method: The notification method in TradingView (either 'Send Plain Text' or 'Webhook URL') is not configured correctly.

My signals are received but fail to execute on my broker. What's wrong?

Check your WebhookTrade dashboard. The "Summary" column will provide a specific error message from the broker. The most common errors are:

• Inactive: Your trial period has ended, or your subscription was canceled or failed to renew. Please visit the Subscription page to activate your plan.
• Invalid Action: This error is triggered if the action command received is not one of the five required values: buy, sell, close_sell, close_buy, or close_all. Additionally, the error can occur if the system receives an unresolved placeholder from TradingView (like {{strategy.order.action}}), indicating the alert was fired without a specific trade action to execute.
• Invalid Symbol: The symbol you sent does not exactly match what your broker uses. Check your broker's platform or the Market Watch in MetaTrader for the correct name. For example, some brokers use different symbols, such as XAUUSD.s instead of XAUUSD.
• Invalid Stops: Your Take Profit or Stop Loss is too close to the current market price. Brokers have a minimum distance requirement. For MetaTrader, ensure your sl_distance or tp_distance is in Points and is large enough to be outside the broker's minimum stop level. For Capital.com, ensure the value is a valid price difference.
• Not Enough Money / Size Too Large: You do not have enough margin in your account to cover the trade size. Try a smaller size and ensure you understand the lot/contract value for the asset.
• User Not Logged In (MetaTrader): Your MetaTrader account is disconnected. Go to the "Connect to MetaTrader" page and re-establish the connection.

I'm receiving duplicate signals for a single trade.

This is almost always caused by your TradingView setup. Check for these two issues:

• You have a duplicate alert in TradingView that you forgot to disable.
• You have enabled both the "Webhook URL" and "Send plain text" notification methods within the *same* alert. You must only use one method per alert.

To diagnose, check the "Logs" tab in your TradingView panel. It will show you exactly how many alerts are being triggered.

My MetaTrader account connection failed.

This is usually due to incorrect credentials or an expired account. To troubleshoot:

• Verify Credentials Manually: The best test is to try logging into the MetaTrader desktop terminal on your computer with the exact same credentials. This will confirm if they are correct.
• Check the Server Name: Do not use a generic name like "Exness". You must use the precise server name provided by your broker, which looks like Exness-MT5Trial7.
• Use the Master Password: Ensure you are using the master/trading password provided by your broker, not the investor (read-only) password. It often has a random format like A+k7X38rr4.
• We currently do not support direct connections to MetaQuotes servers (e.g., MetaQuotes-Demo accounts) due to instability. You must use a demo or real account from a broker. Creating a broker demo account is fast and free.

If you can log in successfully on your desktop but still can't connect on our platform, please contact our support team.

New MetaTrader signals are not closing my old positions.

By default, MetaTrader operates in "Hedge Mode," meaning a new SELL order will open as a separate position instead of closing an existing BUY order. To change this, use our smart netting feature by adding "execution_mode": "close_opposite" to your JSON message. This will first close any positions in the opposite direction before opening a new one. See Section 4.6 for a full explanation.

How can I implement a "reversal" or "flip" strategy?

Use the "execution_mode": "close_opposite" parameter. For this to work effectively as a flip, ensure your alert's trade size is large enough to both close the old position and open a new one. For example: Start with a BUY position of 0.5 lots (you can open this with our Alert Simulator). Your strategy alerts should then be set for a size of 1.0 lot. When the next SELL signal for 1.0 lot arrives, the system will close the 0.5 lot BUY position and open a new 0.5 lot SELL position. When the following BUY signal for 1.0 lot arrives, it will close the 0.5 lot SELL and open a new 0.5 lot BUY.

Can I close only part of my position (partial close)?

• On Capital.com: Yes. Because it operates in netting mode, sending an opposing trade for a smaller size will partially reduce your existing position.
• On MetaTrader: Not directly on a single trade. While you can close one whole position if you have several open, you cannot partially close a single position (e.g., close 0.5 lots of a 1.0 lot trade). The best workaround is to open your initial trade as multiple smaller positions (e.g., three 0.1 lot trades instead of one 0.3 lot trade). This allows you to close them one by one.

My MetaTrader account got disconnected.

This can happen if your demo account expired or if there was temporary instability with your broker's server. The first step is to go to the "Connect with MetaTrader" page and reconnect your account. If this happens frequently, you may need to create another MetaTrader account or consider a broker with more stable servers.

My alert has a placeholder like `{{...}}` and it's failing. Why?

WebhookTrade only accepts final values (like "buy" or a number for size), not the placeholder text itself. The replacement of placeholders like {{strategy.order.action}} is handled entirely by TradingView before the alert is sent. If our system receives the placeholder, it means TradingView did not replace it. Normally, TradingView replaces standard placeholders correctly without any code changes. However, if you want to send more complex dynamic variables (like a calculated stop loss) or if the standard placeholders are not being replaced, you will likely need to use the alert() function within your Pine Script code to build the JSON message manually. For detailed guidance, please refer to the official Pine Script documentation.

Appendix: Subscription Plans

We offer a free trial to all new users. After the trial, you can choose from the following plans on the "Subscription" page.