# Webhook Reference

## POST /trading/webhook/{uuid}/{password}

> Receive trading signal to execute on TradersPost.

```json
{"openapi":"3.1.1","info":{"title":"TradersPost Webhook for Executing Trades with a Strategy and Subscriptions","version":"1.0.0"},"servers":[{"url":"https://webhooks.traderspost.io","description":"TradersPost Webhook Server"}],"paths":{"/trading/webhook/{uuid}/{password}":{"post":{"summary":"Receive trading signal to execute on TradersPost.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Your unique webhook identifier, we call the uuid. Provided when you copy the entire webhook URL from your strategy dashboard."},{"name":"password","in":"path","required":true,"schema":{"type":"string"},"description":"Your webhook password. Provided when you copy the entire webhook URL from your strategy dashboard."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticker","action"],"properties":{"ticker":{"type":"string","description":"The ticker symbol of the financial instrument (e.g., `AAPL`, `SPY 250624C596`, `MNQU2025`, `BTCUSD`).\n\n**Note:** For futures contracts, continuous symbols like NQ1! are automatically mapped to the front-month contract according to our rollover schedule. Since this schedule may differ from other platforms like TradingView, we strongly recommend using explicit futures contract symbols rather than continuous symbols."},"action":{"type":"string","enum":["buy","sell","exit","cancel","add"],"description":"The action or signal type used to determine what type of order to execute.\n\n**Note:** when you are trading put options, the action is inverted. So this means `action=buy` will sell to open short puts and `action=sell` will buy to open long puts. This is necessary when you are running a strategy on the underlying chart but you are buying and selling puts instead of shares."},"sentiment":{"type":"string","enum":["bullish","bearish","flat"],"description":"Optional and often used with TradingView strategies. The expected position sentiment after trade execution:\n* bullish - Open position after trade should be bullish or flat\n* bearish - Open position after trade should be bearish or flat\n* flat - No position should be open after trade execution"},"signalPrice":{"type":"number","format":"float","description":"The market price at the time your alert is triggered (**RECOMMENDED**).\n\nFor TradingView alerts, you can pass this using the `{{close}}` placeholder in your alert message.\n\nThis is first used to create dynamic take profit and stop loss levels and is required when the broker doesn't provide market data (like Tradovate). This value also helps calculate slippage - the difference between the alert price and the actual fill price - allowing you to monitor execution quality.\n\nThe slippage calculation will fall back to `signalPrice`, `price`, `limitPrice`, or `stopPrice` in that order."},"orderType":{"type":"string","enum":["market","limit","stop","stop_limit","trailing_stop"],"description":"The type of order to create. If you send an order type not supported by your broker, it will fallback to the default order type configured in the strategy subscription settings."},"limitPrice":{"type":"number","format":"float","description":"When `orderType=limit` or `orderType=stop_limit` you can send a `limitPrice` for the order.\n\n* If you omit this value, the current market price will be used when the trade is executed\n* This price is also used to calculate slippage (see the `price` property)"},"stopPrice":{"type":"number","format":"float","description":"When `orderType=stop` or `orderType=stop_limit` you can send a `stopPrice` for the order. If you omit this value, the current market price will be used when the trade is executed. This is also used to calculate slippage (see the `price` property)."},"trailAmount":{"type":"number","format":"float","description":"For trailing stop orders (`orderType=trailing_stop`), specifies the fixed dollar amount to trail the market price. The stop price will maintain this absolute dollar offset - for example, with $1.00, it stays $1.00 below the highest price for longs or above the lowest price for shorts. Note: Only one of `trailAmount` or `trailPercent` can be used."},"trailPercent":{"type":"number","format":"float","description":"For trailing stop orders (`orderType=trailing_stop`), specifies the percentage to trail the market price. The stop price will maintain this percentage offset from the highest/lowest price reached. Note: Only one of `trailAmount` or `trailPercent` can be used."},"interval":{"type":"string","description":"The time interval (timeframe/resolution) of the chart that the alert is created on. For TradingView alerts, you can use the {{interval}} placeholder. This value is used for troubleshooting and support purposes."},"quantityType":{"type":"string","enum":["fixed_quantity","dollar_amount","risk_dollar_amount","percent_of_equity","percent_of_position"],"description":"The type of the value sent in the quantity field. Supported values are:\n* fixed_quantity - A fixed quantity number that is used for the order\n* dollar_amount - Dynamically calculates a quantity for the given dollar amount\n* risk_dollar_amount - Dynamically calculates a quantity for the given risk dollar amount. This type requires a stop loss\n* percent_of_equity - Dynamically calculates a quantity for the given percent of equity\n* percent_of_position - Dynamically calculates a quantity for the given percent of position\nDefault is fixed_quantity when you send a quantity without a quantityType."},"quantity":{"type":"number","description":"The quantity to enter. If you omit this value, the quantity will be dynamically calculated based on your strategy subscription settings or defaulted to 1."},"takeProfit":{"$ref":"#/components/schemas/TakeProfit"},"stopLoss":{"$ref":"#/components/schemas/StopLoss"},"timeInForce":{"type":"string","enum":["day","gtc","opg","cls","ioc","fok"],"description":"The time in force for your order. If you send a time in force not supported by your broker, it will fallback to the default time in force or the time in force configured in the strategy subscription settings.\n\nThe supported values are:\n* day - Good For Day\n* gtc - Good Until Canceled\n* opg - Market on Open / Limit on Open\n* cls - Market on Close / Limit on Close\n* ioc - Immediate or Cancel\n* fok - Fill or Kill"},"time":{"type":"string","format":"date-time","description":"ISO-8601 timestamp indicating when the signal was generated (e.g. '2024-01-15T14:30:00Z'). When using TradingView, you can use the `{{timenow}}` placeholder. This timestamp is used to calculate the latency between signal generation and trade execution, which can be viewed in the trade signal logs."},"ignoreTradingWindows":{"type":"boolean","description":"Ignore the defined trading windows in the strategy subscription settings and allow the trade to execute even if it is currently outside of the trading windows."},"cancel":{"type":"boolean","description":"Explicitly control whether or not to cancel open orders before submitting new orders to your broker."},"extendedHours":{"type":"boolean","description":"(STOCKS and OPTIONS SPECIFIC): Whether or not to send the order as an extended hours order. This is only applicable for stocks and the supported values are either true or false."},"test":{"type":"boolean","description":"When set to true, the signal will be processed and validated but no orders will be submitted to your broker. This is useful for testing your webhook integration and verifying that your JSON payload is correct without risking real trades."},"optionType":{"type":"string","enum":["both","call","put"],"description":"(OPTIONS SPECIFIC): The type of option contract to trade. The supported values are both, call and put."},"intrinsicValue":{"type":"string","enum":["itm","otm"],"description":"(OPTIONS SPECIFIC): The intrinsic value of the option contract to trade. The supported values are itm (in the money) and otm (out of the money)."},"expiration":{"type":"string","description":"(OPTIONS SPECIFIC): The expiration of the option contract to trade. The value can be a specific date like 2024-05-06 or a relative date expression like +6 months."},"strikeCount":{"type":"integer","description":"(OPTIONS SPECIFIC): How many strikes to ask for from the broker when executing options trades and scanning the option chain to find a contract to trade."},"strikesAway":{"type":"integer","description":"(OPTIONS SPECIFIC): How many strikes away from at the money to select."},"strikePrice":{"type":"integer","format":"float","description":"(OPTIONS SPECIFIC): Specifies the strike price of the option contract to trade."},"extras":{"type":"object","additionalProperties":true,"description":"Custom metadata for any additional logging needs (optional). We recommend putting whatever you like in this property so they don't conflict with the other properties."}}}}}},"responses":{"200":{"description":"Successfully received webhook.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"logId":{"type":"string"},"payload":{"type":"object","properties":{"ticker":{"type":"string"},"action":{"type":"string"},"sentiment":{"type":"string"},"signalPrice":{"type":"number","format":"float"},"quantity":{"type":"number"},"quantityType":{"type":"string"},"orderType":{"type":"string"},"time":{"type":"string","format":"date-time"},"test":{"type":"boolean"},"takeProfit":{"type":"object"},"stopLoss":{"type":"object"},"extras":{"type":"object","additionalProperties":true}}}},"required":["success","id","logId","payload"]}}}},"400":{"description":"Bad Request - The JSON that gets sent to TradersPost has to be precisely accurate in order for us to accept it. It is important to pay attention all the details, all the little characters have meaning and are important.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"logId":{"type":"string","description":"Optional log identifier for tracking the request. May not be present for certain types of errors (e.g., authentication failures, malformed requests)."},"messageCode":{"type":"string","enum":["post-required","empty-json","malformed-json","invalid-payload","invalid-action","invalid-sentiment","invalid-sentiment-action","invalid-order-type","invalid-trailing-stop","invalid-option-type","invalid-intrinsic-value","invalid-expiration","invalid-strike-count","invalid-strikes-away","invalid-strike-price","not-trading-view","not-trend-spider","invalid-ip-address","invalid-ip-address-format","ticker-does-not-exist","invalid-ticker-and-option-type","invalid-password","empty-ticker-name","unsupported-ticker","invalid-quantity-type","invalid-quantity-type-action","invalid-risk-dollar-amount-action","invalid-percent-of-position-action","quantity-type-requires-quantity","invalid-quantity-type-for-asset-class","invalid-quantity","invalid-time-in-force","invalid-extended-hours","invalid-asset-class","invalid-take-profit-percent","invalid-take-profit-amount","invalid-take-profit-limit-price","invalid-take-profit-amount-and-percent","invalid-take-profit-relative-and-absolute","invalid-take-profit-value-required","invalid-stop-loss-type","invalid-stop-loss-percent","invalid-stop-loss-amount","invalid-stop-loss-stop-price","invalid-stop-loss-limit-price","invalid-stop-loss-trail-price","invalid-stop-loss-trail-amount","invalid-stop-loss-trail-percent","invalid-stop-loss-trail-value","invalid-stop-loss-trail-value-required","invalid-stop-loss-amount-and-percent","invalid-stop-loss-relative-and-absolute","invalid-stop-loss-stop-price-required","invalid-stop-loss-value-required","invalid-expires-at","invalid-message-length","invalid-message-tags"],"description":"Specific error code indicating the type of validation error encountered."},"message":{"type":"string","description":"Human-readable error message explaining the validation error."}},"required":["success","messageCode","message"]}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messageCode":{"type":"string"},"message":{"type":"string"}},"required":["success","messageCode","message"]}}}},"500":{"description":"Internal server error. Sometimes an HTML response might come back, but it's best just to reply on the 500 status code."}}}}},"components":{"schemas":{"TakeProfit":{"type":"object","description":"Optional take profit configuration for the trade. If omitted, no take profit will be placed. It will be ignored if the broker or exchange does not support bracket orders. IMPORTANT: The signal take profit will only be used if you check Use signal take profit in the strategy subscription settings in TradersPost. For examples, see https://docs.traderspost.io/docs/core-concepts/webhooks#take-profit","properties":{"limitPrice":{"type":"number","format":"float","description":"Absolute limit price calculated on the webhook sender side."},"percent":{"type":"number","format":"float","description":"Relative percentage take profit to calculate relative to entry price. The entry price for market orders is estimated based on the mid point between the bid and ask on the most recent quote."},"amount":{"type":"number","format":"float","description":"Relative dollar amount take profit to calculate relative to entry price. The entry price for market orders is estimated based on the mid point between the bid and ask on the most recent quote."}}},"StopLoss":{"type":"object","description":"Optional stop loss configuration for the trade. If omitted, no stop loss will be placed. It will be ignored if the broker or exchange does not support bracket orders. IMPORTANT: When using market orders and you are calculating a relative stop loss price, TradersPost will fetch a quote from your broker and use the price from the quote as the entry price in order to calculate the stop loss stop price since with markets orders, we don't know the price you will be filled at so we have to use the quote price. For examples, see https://docs.traderspost.io/docs/core-concepts/webhooks#stop-loss","properties":{"type":{"type":"string","enum":["stop","stop_limit","trailing_stop"],"description":"Type of stop loss. If provided, overrides the stop loss type configured in strategy subscription settings."},"percent":{"type":"number","format":"float","description":"Relative percentage stop loss to calculate relative to entry price."},"amount":{"type":"number","format":"float","description":"Relative dollar amount stop loss to calculate relative to entry price."},"stopPrice":{"type":"number","format":"float","description":"Absolute stop price calculated on the webhook sender side."},"limitPrice":{"type":"number","format":"float","description":"Absolute limit price calculated on the webhook sender side. Requires type to be set to stop_limit."},"trailAmount":{"type":"number","format":"float","description":"Dollar value away from the highest water mark. For a sell trailing stop, stop price is always hwm - trailAmount. Requires type to be set to trailing_stop."},"trailPercent":{"type":"number","format":"float","description":"Percent value away from the highest water mark. For a sell trailing stop, stop price is always hwm * (1 - trailPercent/100). Requires type to be set to trailing_stop."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.traderspost.io/docs/developer-resources/webhook-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.