Webhook Setup

Webhooks are HTTP endpoints that receive trading signals from external sources. This guide covers everything you need to know about setting up and using webhooks.

Understanding Webhooks

A webhook is a URL that accepts incoming HTTP requests. When your signal source (TradingView, custom script, etc.) sends a request to this URL, TradeStaq processes the signal and executes the trade.

Your Signal Source → HTTP POST → Webhook URL → TradeStaq → Exchange

Your Webhook URL

Each Signal Bot has a unique webhook URL:

https://www.tradestaq.com/api/webhooks/trade/{webhookId}

Finding Your Webhook URL

1. Go to Dashboard → Signal Bots
2. Click on your bot
3. Navigate to the Webhook tab
4. Click Copy to copy the URL

Note: Keep your webhook URL private. Anyone with this URL can send signals to your bot.

Signal Templates

Minimum Required (2 fields)

The simplest signal that will work. Uses your bot's configured position size and executes at market price.

{
  "ticker": "BTCUSDT",
  "position": "long"
}

Recommended

Includes the current price to speed up position size calculations (reduces API calls).

{
  "ticker": "BTCUSDT",
  "position": "long",
  "marketPrice": "97500",
  "comment": "RSI oversold entry"
}

Full Control

Override all settings per signal for maximum control.

{
  "ticker": "BTCUSDT",
  "position": "long",
  "size": "0.1",
  "marketPrice": "97500",
  "tp": "100000",
  "sl": "95000",
  "leverage": "10",
  "comment": "Manual entry",
  "exchange": "binance"
}

Field Reference

Required Fields

These fields must be present in every signal.

Optional Fields

These fields customize the trade execution. If omitted, bot settings are used.

Detailed Field Descriptions

ticker (Required)

The trading symbol for the pair you want to trade.

Accepted formats:

• BTCUSDT - Simple format
• BTC/USDT - With slash separator
• BTC-USDT - With dash separator (auto-converted)

The system automatically normalizes the symbol for your exchange. For example, BTC/USDT becomes BTC/USDT:USDT for futures on most exchanges.

position or action (Required)

Determines the trade action to execute. You can use either position or action as the field name - they work identically.

TradingView Tip: Use {{strategy.market_position}} (outputs long, short, flat) with the position field, or use {{strategy.order.action}} (outputs buy, sell) with the action field.

size (Optional)

Override the bot's configured position size for this specific trade.

Examples:

• "0.1" - Trade 0.1 contracts/coins
• "100" - Trade 100 units
• "10%" - Trade 10% of available balance (if supported)

If omitted, the bot uses its configured position sizing (percentage of balance or fixed amount).

marketPrice (Optional)

The current market price of the asset. Used internally for:

• Calculating position size when using percentage-based sizing
• Reducing API calls to the exchange

Important: This is different from price (which would trigger a limit order). marketPrice is purely informational for calculations.

tp (Optional)

Take profit price. When set, a take profit order is placed after the entry is filled.

Example: If entering long at $97,500, setting "tp": "100000" places a sell limit at $100,000.

sl (Optional)

Stop loss price. When set, a stop loss order is placed after the entry is filled.

Example: If entering long at $97,500, setting "sl": "95000" places a stop market at $95,000.

leverage (Optional)

Override the leverage for this trade. Only applies to futures/margin trading.

Example: "leverage": "10" sets 10x leverage for this position.

comment (Optional)

A custom note that appears in Telegram notifications. Useful for identifying why a trade was taken.

Examples:

• "RSI oversold bounce"
• "TP1 hit"
• "Stop loss triggered"

exchange (Optional)

Target a specific exchange when your bot has multiple exchanges connected.

Matching rules:

• Matches by exchange name: "binance", "bybit"
• Matches by account label: "Main Account", "DCA Account"
• Case-insensitive partial matching

If omitted, the signal executes on all connected exchanges.

timeframe (Optional)

The chart timeframe the signal came from. Used for timeframe validation if enabled in your subscription tier.

Examples: "1" (1 minute), "60" (1 hour), "D" (daily)

action (Optional)

An alias for position. Use this with TradingView's {{strategy.order.action}} placeholder which outputs buy or sell.

Value mapping:

• buy → Opens a long position (same as long)
• sell → Opens a short position (same as short)

Note: If both position and action are provided, position takes precedence.

strategy (Optional)

The strategy name that generated this signal. Displayed in notification subjects and activity logs.

Use cases:

• Identifying signal source in Telegram notifications
• Filtering and organizing signals in activity logs
• Tracking performance by strategy name

Example: "strategy": "RSI Scalper" or "strategy": "Golden Cross Bot"

price (Optional)

Set a specific price to place a limit order instead of a market order. When omitted, a market order is placed.

Example: "price": "95000" places a limit order at $95,000 instead of executing at market price.

Note: Limit orders may not fill immediately or at all if the price doesn't reach your specified level.

Position Values Explained

Sending Signals

Using cURL

curl -X POST https://www.tradestaq.com/api/webhooks/trade/YOUR_WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -d '{"ticker": "BTCUSDT", "position": "long"}'

Using Python

import requests

webhook_url = "https://www.tradestaq.com/api/webhooks/trade/YOUR_WEBHOOK_ID"

signal = {
    "ticker": "BTCUSDT",
    "position": "long",
    "marketPrice": "97500",
    "comment": "Python script entry"
}

response = requests.post(webhook_url, json=signal)
print(response.json())

Using JavaScript

const webhookUrl = "https://www.tradestaq.com/api/webhooks/trade/YOUR_WEBHOOK_ID";

const signal = {
  ticker: "BTCUSDT",
  position: "long",
  marketPrice: "97500",
  comment: "JS entry"
    openGraph: { title: 'Webhook Setup', description: 'How to configure webhooks for signal bot triggers on TradeStaq.' },
};

fetch(webhookUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(signal)
})
  .then(res => res.json())
  .then(data => console.log(data));

Response Codes

Success Response

{
  "success": true,
  "message": "Signal received",
  "signalId": "abc123"
}

Error Response

{
  "success": false,
  "error": "Invalid action specified",
  "code": "INVALID_ACTION"
}

Rate Limits

To prevent abuse, webhooks have rate limits:

Note: If you hit rate limits, your signals will be rejected. Reduce signal frequency or contact support for higher limits.

Testing Your Webhook

Built-in Test Tool

1. Go to your bot's detail page
2. Navigate to the Webhook tab
3. Your webhook URL is displayed with a copy button
4. Use the Signal Logs tab to verify signals are received

Manual Testing

Test with cURL before connecting your actual signal source:

# Test long signal
curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"ticker": "BTCUSDT", "position": "long"}'

# Test close signal
curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"ticker": "BTCUSDT", "position": "flat"}'

Webhook Health Monitoring

The bot card shows webhook health based on signal activity:

Note: Monitor webhook health to ensure your signals are being received. A stale webhook may indicate an issue with your signal source.

Common Issues

"Invalid JSON"

Problem: Malformed JSON in request body

Solution: Validate your JSON at jsonlint.com

// Wrong - missing quotes
{ticker: BTCUSDT}

// Correct
{"ticker": "BTCUSDT", "position": "long"}

"Missing ticker or position"

Problem: Required fields not present

Solution: Ensure both ticker and position fields are included

"Bot Not Active"

Problem: Signal sent to paused/stopped bot

Solution: Activate the bot before sending signals

"Rate Limit Exceeded"

Problem: Too many signals in short period

Solution: Reduce signal frequency, implement backoff

Security Best Practices

1. Keep URL Private

• Never share your webhook URL publicly
• Don't commit it to public repositories
• Use environment variables in code

2. Regenerate If Compromised

If your webhook URL is exposed:

1. Delete the bot
2. Create a new bot
3. Update your signal source with new URL

3. Monitor Activity

• Check activity logs regularly
• Set up Telegram alerts for trade notifications
• Review webhook health indicators

Integration Examples

• TradingView Integration
• Pine Script Examples