> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe — TradingView Webhook Integration

> Connect TradingView's Pine-Script alerts to your unCoded SignalsBot. Use external charting setups to drive your bot.

<Info>
  **TradingView webhook integration lets you drive your unCoded bot from TradingView's Pine-Script alerts.** Author your strategy in TradingView's chart-based environment, set up alerts, and have them fire webhooks to your SignalsBot. Useful when you have an existing TradingView setup or prefer Pine Script's expressiveness over the SignalEditor's canvas.
</Info>

## When to pick this recipe

<CardGroup cols={2}>
  <Card title="You have an existing TradingView strategy" icon="chart-line">
    You've authored Pine Script strategies in TradingView, validated them with TradingView's tools, and want to automate the execution.
  </Card>

  <Card title="You prefer Pine Script over the SignalEditor canvas" icon="code">
    Pine Script offers expressiveness the SignalEditor's drag-and-drop canvas doesn't. If you're comfortable with code-style strategy authoring, this is the path.
  </Card>

  <Card title="You want to leverage external charting" icon="window-maximize">
    TradingView's chart-based experience is unmatched. Strategy ideas that you've worked out visually on charts can drive the bot via webhooks.
  </Card>

  <Card title="You're integrating signals from a third party" icon="rss">
    Some signal providers publish TradingView alerts. The recipe shows you how to wire those into your bot.
  </Card>
</CardGroup>

## When NOT to pick this recipe

<Warning>
  * ❌ **You don't have a TradingView paid plan** — webhook alerts are a paid TradingView feature (Pro and above).
  * ❌ **First-week operators** — get comfortable with modes and SignalEditor recipes first.
  * ❌ **You don't trust the third-party signal source** — webhook recipients can change configuration. Trust assessment first.
  * ❌ **You want everything to live on your VPS** — TradingView webhooks involve a third party (TradingView's servers). Latency and reliability are out of your control.
</Warning>

## Prerequisites

<Steps>
  <Step title="TradingView Pro+ subscription">
    Webhooks are a paid feature. Verify your plan supports webhook alerts.
  </Step>

  <Step title="SignalsBot deployed and reachable">
    Behind a TLS reverse proxy with a real DNS name (e.g., `signals.yourdomain.com`).
  </Step>

  <Step title="Webhook secret set">
    `TRADINGVIEW_WEBHOOK_SECRET` environment variable on the SignalsBot. Generate with `openssl rand -hex 32`.
  </Step>

  <Step title="Mode running on the target pair">
    The recipe gates buying on the mode. The mode itself must be configured first.
  </Step>
</Steps>

## Setup steps

<Steps>
  <Step title="Author your TradingView strategy">
    On TradingView, open your symbol's chart. Apply your Pine Script strategy or use a built-in indicator.

    Example: a simple RSI alert that fires when RSI(14) crosses below 30.
  </Step>

  <Step title="Create an alert">
    Click the alarm clock icon → "Create Alert."
  </Step>

  <Step title="Configure the alert condition">
    Set the condition matching your strategy logic. For RSI \< 30 example: "RSI" → "Crossing Down" → `30`.
  </Step>

  <Step title="Set the alert to fire on bar close">
    Critical: select "Once Per Bar Close" to avoid intra-bar firing.
  </Step>

  <Step title="Set the webhook URL">
    In the alert dialog, scroll to "Notifications" → "Webhook URL." Paste your SignalsBot endpoint:

    ```text theme={null}
    https://signals.yourdomain.com/webhook
    ```
  </Step>

  <Step title="Set the alert message body">
    The message body becomes the webhook payload. Set it to JSON:

    ```text theme={null}
    {
      "secret": "<your-shared-secret>",
      "pair": "BTCUSDT",
      "mode": 4,
      "canBuy": true
    }
    ```

    Replace `<your-shared-secret>` with the value you generated. TradingView allows variable substitution (`{{ticker}}`, `{{close}}`, etc.) — you can use these to make the message dynamic.
  </Step>

  <Step title="Save the alert">
    The alert is now active and will fire when the condition holds.
  </Step>

  <Step title="Build the mirror exit alert">
    Create a second alert with opposite condition (RSI > 70 or whatever your exit signal is) and webhook payload writing `canBuy: false`. This brackets the buying windows.
  </Step>

  <Step title="Test with a manual trigger">
    Use TradingView's "Once" alert option to fire a single test alert. Verify it lands at the SignalsBot:

    * SignalsBot's audit log shows the accepted webhook.
    * Dashboard's mode panel shows `canBuy` flipped accordingly.
  </Step>

  <Step title="Forward-test on small capital">
    Allocate `$1,500–$3,000` to the mode. Run for 2–4 weeks observing the alerts firing and the bot's response. Compare against TradingView's signal log to confirm no missed alerts.
  </Step>

  <Step title="Promote to full capital if validated">
    Once forward-test confirms reliability, scale to full mode capital.
  </Step>
</Steps>

## TradingView webhook reliability

<AccordionGroup>
  <Accordion title="Latency" icon="clock">
    TradingView webhook delivery typically arrives within `1–10` seconds of the alert firing. Acceptable for most timeframe-driven strategies.

    Don't use this for high-frequency scalping where seconds matter. The latency floor is too high.
  </Accordion>

  <Accordion title="Delivery guarantees" icon="paper-plane">
    TradingView retries failed webhook deliveries. Retries are typically idempotent (same message), so duplicate handling at the SignalsBot is graceful.

    However: TradingView is not a hard delivery guarantee. Outages or quirks can cause missed alerts. Don't depend on TradingView for safety-critical signals.
  </Accordion>

  <Accordion title="Source IP authentication" icon="shield">
    TradingView's webhook source IPs are public (TradingView documents them). For tighter security, you can IP-allowlist these IPs at your reverse proxy.

    Trade-off: TradingView occasionally adds new source IPs, requiring you to update the allowlist.
  </Accordion>

  <Accordion title="Pine Script alert variables" icon="code">
    TradingView's alert message can include Pine variables: `{{ticker}}`, `{{close}}`, `{{strategy.position_size}}`, etc. Use these to include dynamic data in your webhook payload.

    Example: `"price": {{close}}` includes the closing price at alert time.
  </Accordion>
</AccordionGroup>

## Common mistakes

<AccordionGroup>
  <Accordion title="❌ Forgetting 'Once Per Bar Close' in alert settings" icon="ban">
    Default alert mode is "Once Per Bar" — fires intra-bar on first condition met. Floods the SignalsBot if condition holds for the full bar.

    **Fix**: explicitly select "Once Per Bar Close."
  </Accordion>

  <Accordion title="❌ Hardcoding secret in shared repo" icon="ban">
    The shared secret is included in TradingView's alert message. If you save your TradingView strategy publicly (TradingView's strategy share feature), the secret leaks.

    **Fix**: keep your TradingView strategies private, or use placeholder secrets in shared versions.
  </Accordion>

  <Accordion title="❌ Not building the exit alert" icon="ban">
    Like other recipes — without the OFF mirror, flags stay flipped forever once entered.

    **Fix**: pair every entry alert with an exit alert.
  </Accordion>

  <Accordion title="❌ Trusting third-party TradingView signals without audit" icon="ban">
    If you're using a third-party Pine Script signal, they have webhook authority over your bot. Audit their signals weekly via the SignalsBot's audit log.

    **Fix**: don't subscribe to opaque "AI signal" providers. Use TradingView strategies you understand.
  </Accordion>

  <Accordion title="❌ Skipping the SignalsBot's TLS proxy" icon="ban">
    TradingView webhooks travel the public internet. Without TLS, your shared secret is in the clear.

    **Fix**: TLS reverse proxy is mandatory.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="SignalsBot" icon="satellite-dish" href="/modules/signalsbot">
    The receiver TradingView posts to.
  </Card>

  <Card title="API Key Security" icon="shield" href="/exchanges/api-key-security">
    Webhook secret hygiene principles.
  </Card>

  <Card title="RSI Mean-Reversion" icon="circle-down" href="/strategies/recipes/rsi-mean-reversion">
    Native SignalEditor alternative — same logic without TradingView.
  </Card>

  <Card title="Architecture" icon="server" href="/concepts/architecture">
    How webhooks fit into the overall system.
  </Card>
</CardGroup>