# Webhooks
**Connect TradingView to Viper's execution algorithms.**
Webhooks let you trigger Viper executions from external signals — primarily TradingView alerts. Your Pine Script strategy detects the setup. Viper handles the execution. The alert fires a POST request to a unique URL, and Viper launches whichever algorithm you've configured with the size, side, and parameters you've defined in advance.
The result is the same execution quality you get from the platform — passive fills, controlled market impact, maker fee optimization — triggered automatically from your own technical analysis, without opening the browser.
***
## What They Solve
TradingView's native alert system can place orders directly on some exchanges, but only as raw market orders. On Hyperliquid's transparent orderbook, that means sweeping the book at taker fees with your full size visible to everyone running L4 data.
Webhooks bridge the gap. TradingView handles signal generation — the chart patterns, indicator crossings, and Pine Script conditions you've already built. Viper handles execution — the stealth, the passive fills, the fee optimization. Each system does what it's best at.
This also decouples your signal logic from your execution logic. You can change your entry strategy in Pine Script without touching your execution configuration, or switch from GlideMaker to Pacemaker without rewriting your alerts.
***
## How It Works
Every webhook has a unique URL containing a cryptographic token. When TradingView fires an alert, it sends a POST request to that URL. Viper validates the token, merges any payload overrides onto your pre-configured defaults, resolves credentials, and launches the execution.
The webhook configuration defines the defaults: instrument, side, size, algorithm, algo parameters, and safety controls. The TradingView alert payload can optionally override specific fields — side, symbol, or algo parameters — but doesn't have to. If everything is pre-configured in Viper, the alert body can be empty (`{}`).
Two action patterns are supported:
**Execute** launches an algorithm immediately when the alert arrives. This is the primary pattern — TradingView signal in, algo execution out.
**Arm Monitor** enables a pre-configured [Trade Monitor](https://docs.viperexecution.com/features/trade-monitors) instead of executing directly. The monitor's own volume and flow conditions then gate the actual execution. This is a two-stage confirmation: TradingView says "the setup is forming," the monitor says "the flow confirms it." An optional auto-disarm timeout disables the monitor if conditions aren't met within a specified window.
***
## Creating a Webhook
Open **Webhooks** in the navigation and click **Create webhook**.
*The Webhooks page before any webhooks are configured. Create your first webhook to connect TradingView alerts to Viper execution.*
The creation form configures everything the webhook needs to execute.
**Name** identifies the webhook in your list and in Telegram notifications. Use something descriptive — "BTC Long Entry" or "ETH Mean Reversion Short."
**Action type** selects Execute (launch algo immediately) or Arm Monitor (enable a trade monitor and let its conditions gate execution).
**Symbol** sets the instrument. The searchable dropdown shows all Hyperliquid perpetuals and spot markets with live 24h stats. If left empty, the symbol must come from the TradingView payload.
**Side** can be fixed (Buy or Sell) or Dynamic. Dynamic side must be provided by the TradingView alert — useful for strategies that generate both long and short signals from the same alert.
**Size** supports three modes: fixed USD (converted to coin quantity at trigger-time price), fixed coin size, or percentage of available margin. The percentage slider and balance display show exactly how much of your account each webhook would commit. Minimum $200 for algo executions, $10 for market orders.
**Algorithm** selects the execution engine: [GlideMaker](https://docs.viperexecution.com/algorithms/glidemaker), [GhostSweep](https://docs.viperexecution.com/algorithms/ghostsweep), [Pacemaker](https://docs.viperexecution.com/algorithms/pacemaker), [FlowScale](https://docs.viperexecution.com/algorithms/flowscale), [FlowBand](https://docs.viperexecution.com/algorithms/flowband), [Smart Exit](https://docs.viperexecution.com/algorithms/smart-exit), or Market. Each algo exposes its full settings panel — strategy presets, price limits, duration, sweep prices — identical to the main trading interface.
**Safety controls** at the bottom set the cooldown period between fires and an optional daily fire cap. Cooldown prevents rapid re-triggering if TradingView sends multiple alerts in quick succession. The daily cap is a hard stop — once reached, all further alerts are rejected until the next UTC day.
*Creating a "BTC Long Entry" webhook — GlideMaker BUY $100,000 with Neutral strategy, $72,000 price limit, post-only enabled. Cooldown set to 60 seconds. The percentage slider shows this represents 74% of available margin.*
***
## Setup Guide
After creating a webhook, the **Setup guide** tab shows everything you need to connect it to TradingView in three steps.
**Step 1** provides the webhook URL — a unique HTTPS endpoint containing the authentication token. Copy it directly into TradingView's webhook URL field.
**Step 2** provides the alert message body — the JSON payload TradingView will send. If all fields are pre-configured in Viper (symbol, side, size, algo), the message body is simply `{}`. If symbol or side are dynamic, the template includes the appropriate TradingView variables (`{{ticker}}` and `{{strategy.order.action}}`).
**Step 3** lets you run a dry test before connecting TradingView. The dry run validates the full pipeline — token lookup, parameter resolution, size calculation — without placing any orders. The result shows exactly what the algo would receive.
*The three-step setup guide. The webhook URL is ready to copy into TradingView. The alert message is `{}` because all parameters are pre-configured. The dry test button validates the full pipeline without executing.*
*Dry test result showing the resolved parameters: BTC BUY via GlideMaker, $100,000 fixed USD resolving to 1.43546 BTC at current price. Status: Ready to fire.*
***
## TradingView Setup
With the webhook URL and alert message copied, switch to TradingView.
### 1. Create the Alert
Open the alert creation dialog on your chart. Set your trigger condition — price level, indicator crossing, or Pine Script strategy signal. Set the trigger frequency (Once Only for single-fire webhooks, or a repeating frequency that matches your webhook's cooldown and daily cap).
*TradingView alert on BTCUSDT.P — triggering when price falls below $69,200. Set to fire once.*
### 2. Set the Message
Click the **Message** field and paste the alert message from Viper's setup guide. For a fully pre-configured webhook, this is `{}`. For dynamic webhooks, it includes TradingView variables that resolve at alert time.
*The message field with `{}` — all parameters are pre-configured in Viper, so the alert body only needs to be valid JSON.*
### 3. Set the Webhook URL
Click **Notifications**, enable **Webhook URL**, and paste the URL from Viper's setup guide.
*The Viper webhook URL pasted into TradingView's notification settings. TradingView will POST to this URL when the alert condition is met.*
### 4. Activate
Save the alert. It appears in TradingView's alert panel as Active.
*Alert active and monitoring BTCUSDT.P for the price condition.*
### 5. Alert Fires
When the condition is met, TradingView fires the alert and sends the webhook. The alert status changes to Triggered, and the log confirms successful delivery.
*Alert triggered — TradingView detected the price condition and fired the webhook.*
*TradingView's log confirming "Webhook successfully delivered" — the POST request reached Viper and was accepted.*
***
## Execution
Once the webhook is delivered, Viper launches the configured algorithm. The execution appears on the **Strategies** page with a Webhook badge, running identically to any manually-launched algo — same execution chart, same fill tracking, same metrics.
*GlideMaker BUY 1.43546 BTC ($100,000) running on the Strategies page — launched by the TradingView webhook. The Webhook badge appears alongside the Glidemaker and Post tags. Execution is 68% filled after 2m 46s, with 100% maker fills and +2.82bps vs arrival. The execution chart shows maker fills (cyan dots) tracking market price with a $72,000 price limit.*
***
## Fire History
Every webhook fire — live or dry run — is logged with full detail. The **Fire history** tab shows a chronological list with expandable entries.
Each entry records: timestamp, success/failure, latency (time from request received to algo launched), execution ID (clickable link to the Strategies page), source IP, the raw payload from TradingView, and the resolved parameters after merging payload onto config defaults.
*Fire history showing two entries: the live fire (Success, 309ms latency, execution ID linked) and the earlier dry run. The expanded detail shows source IP, empty payload (all params pre-configured), resolved parameters, and the execution ID for the running GlideMaker.*
*Dry run entry expanded — showing the full resolved parameters that the algo would receive. Useful for validating configuration before connecting TradingView.*
The **Export JSON** button downloads the complete fire log with all fields for external analysis or record-keeping.
***
## Payload Overrides
The TradingView alert message can override any field defined in the webhook configuration. The merge priority is: payload overrides config. This lets you create flexible webhooks where some parameters are fixed and others come from the alert.
**Fields that can be overridden from the payload:**
| Field | Description | Example |
| ------------------ | -------------------------------------- | ------------------------------------------------ |
| `symbol` | Trading instrument | `"BTC"`, `"ETH"`, `"{{ticker}}"` |
| `side` | Trade direction | `"buy"`, `"sell"`, `"{{strategy.order.action}}"` |
| `size` | Trade size (uses webhook's size\_type) | `50000` |
| `algo_type` | Override algorithm | `"pacemaker"`, `"ghostsweep"` |
| `reduce_only` | Close-only mode | `true` |
| `strategy` | Algo preset | `"passive"`, `"aggressive"` |
| `limit_price` | Price limit | `72000` |
| `duration_seconds` | Pacemaker duration | `600` |
Algo-specific parameters can be passed either in a nested `algo_params` object or as top-level fields. Top-level fields are merged into `algo_params` automatically.
Example: fully dynamic webhook
A single webhook can handle multiple instruments and directions if the payload provides the varying fields:
**Webhook config:** Size $50,000 USD, GlideMaker, Neutral strategy, 60s cooldown. Symbol and side left empty (dynamic).
**TradingView alert message:**
```json
{
"symbol": "{{ticker}}",
"side": "{{strategy.order.action}}"
}
```
TradingView resolves the variables at alert time. A BTC buy signal becomes `{"symbol": "BTCUSDT.P", "side": "buy"}`. Viper merges this onto the config defaults and launches GlideMaker BUY $50,000 on BTC.
Note: `{{ticker}}` returns the TradingView symbol format (e.g., `BTCUSDT.P`). Viper normalizes common formats, but using Hyperliquid's native symbol names (e.g., `BTC`, `ETH`) in fixed configs is more reliable.
Example: override algo parameters per alert
**Webhook config:** BTC BUY $100,000, GlideMaker, Neutral.
**Alert for aggressive entry:**
```json
{
"strategy": "aggressive",
"limit_price": 75000
}
```
**Alert for patient accumulation:**
```json
{
"strategy": "passive"
}
```
Same webhook, different execution behavior depending on which alert fires.
***
## Arm Monitor Pattern
The second action type — Arm Monitor — connects TradingView signals to Viper's [Trade Monitors](https://docs.viperexecution.com/features/trade-monitors) for two-stage confirmation.
Instead of executing immediately, the webhook enables a pre-configured monitor that was sitting disabled. The monitor's own conditions — volume thresholds, flow patterns, sweep detection — then gate the actual execution. If the flow confirms the setup, the monitor fires and launches the algo. If it doesn't, the monitor can auto-disarm after a configurable timeout.
This is useful when you trust your technical setup but want on-chain flow confirmation before committing capital. TradingView says "price reached my level." The monitor says "$5M of real buying confirms it."
**Auto-disarm** disables the monitor after a specified number of minutes if it hasn't fired. This prevents stale monitors from sitting armed indefinitely after the setup has expired.
**Side override** optionally passes the alert's side through to the monitor's action, so a single monitor can handle both long and short signals.
***
## Safety Controls
**Cooldown** enforces a minimum interval between fires. A webhook in cooldown rejects incoming alerts with a 429 response and a `Retry-After` header. TradingView will show these as failed deliveries. Set cooldown based on your strategy's expected signal frequency — 60 seconds prevents accidental double-fires, longer cooldowns suit strategies that should only trigger once per major move.
**Daily fire cap** limits the total number of successful fires per UTC day. Once reached, all further alerts are rejected until midnight UTC. This prevents runaway execution if your alert condition triggers more frequently than expected.
**Global kill switch** disables all webhooks for your account in a single action. Available in the webhook interface — when enabled, every inbound alert is rejected with a 403 response. The kill switch is independent of individual webhook enable/disable toggles. Use it when you need to halt all automated execution immediately.
**Token regeneration** generates a new webhook URL and immediately revokes the old one. The old URL returns 404 for any subsequent requests. Use this if a token is compromised or if you want to rotate credentials.
***
## Telegram
Webhook fires generate Telegram notifications through Viper's [Telegram integration](https://docs.viperexecution.com/features/telegram). Each fire sends the webhook name, algo type, side, size, symbol, execution ID, and the source message from TradingView. Subsequent algo milestones (25%, 50%, 75%, 100% filled) follow in the same notification stream.
***
## Trade-Offs
Webhooks add a network hop that Trade Monitors don't have. A TradingView alert traverses: TradingView servers → internet → Cloudflare → Viper backend. Typical end-to-end latency is 200–500ms from alert fire to algo launch. Trade Monitors, by contrast, evaluate on the same process as the execution engine with no network transit. For strategies where milliseconds matter, monitors are faster.
Webhooks depend on TradingView's alert delivery infrastructure. If TradingView experiences delays or outages, your alerts may arrive late or not at all. The fire history makes this visible — gaps in expected fires or elevated latency indicate delivery issues on the TradingView side.
The payload override system is flexible but requires valid JSON. TradingView alerts configured with malformed message bodies will be accepted (Viper treats invalid JSON as a plain text message) but field overrides won't work. Always use the dry test to validate your configuration before going live.
For strategies that depend on real-time order flow analysis rather than chart-based signals, [Trade Monitors](https://docs.viperexecution.com/features/trade-monitors) are the right tool. Webhooks are for when the signal source is external to Viper.