Webhook payloads and secrets
Full reference for the TradingView webhook payload format, authentication, and deduplication.
This is the full reference for the TradingView webhook endpoint — covering two authentication methods (body secret and HMAC header), the five payload fields, deduplication behaviour, a rate limit of 30 signals per 60 seconds, and all response codes.
Endpoint
POST /api/webhooks/tradingview/:strategyId
strategyId is the strategy's database ID, visible in the webhook URL shown on the strategy detail page.
How is the webhook authenticated?
Two methods are accepted:
Body secret (recommended for TradingView):
Include a secret field in the JSON body. Coinrule compares it to the stored secret using a constant-time comparison.
{
"secret": "<your-strategy-secret>",
"side": "buy"
}HMAC header (for custom integrations):
Compute HMAC-SHA256(raw_body, secret) and send as the X-Coinrule-Signature header. The body does not need a secret field.
An invalid or missing secret returns 404 Not Found (not 401) to prevent enumeration of valid strategy IDs.
What fields does the payload accept?
| Field | Required | Description |
|---|---|---|
secret | Yes (if no HMAC header) | Your strategy webhook secret |
side | Yes | Trade direction: buy, sell, open_long, close_long, open_short, close_short |
symbol | No | Symbol hint (e.g. {{ticker}}); parsed by the engine |
price | No | Price hint (e.g. {{close}}); used for logging, not order execution |
id | No | Caller-supplied event ID. Reuse it only when retrying the same event. |
The body must be a JSON object. Arrays, null, malformed JSON, and missing or
unrecognized directions return 400 Bad Request without dispatching or using
signal credits. action and signal are accepted as aliases for side, in that
order of precedence. Additional custom fields such as score are allowed.
For a spot agent, buy opens a long position and sell closes its existing
long position. A spot sell with no open position does not place an order.
For perpetual markets, sell retains its short-entry meaning; use close_long
or close_short to request an exit explicitly. Explicit direction commands
such as open_short keep their meaning.
Your agent evaluates each webhook before placing an order. Custom fields such as
score are available to its webhook conditions alongside a normalized signal
value (open_long, open_short, close_long, or close_short). For example, an
agent requiring score >= 0.9 ignores buy signals with a lower or missing score.
Each event is used for that evaluation only; later price updates do not reuse it.
A valid received signal still costs one signal credit when its conditions do not
match and no order is placed.
How does deduplication work?
If you include an id field, a second request to the same agent with that id
within 24 hours returns 200 OK but produces no additional trade. Signal credit
charges are also deduplicated for that agent and event ID. Different agents can
use the same ID independently. Retries of previously billed events retain their
original charge. If no id is provided, a SHA-256 hash of the request body is
used instead. Use a fresh ID for each new event.
What happens to signals while the agent is offline?
Queued signals are processed in the order they arrived when the execution service resumes. An entry followed by an exit is therefore replayed as an entry followed by an exit. The pending queue retains the 100 most recent signals.
What is the rate limit?
30 signals per 60 seconds per strategy. Exceeding this returns HTTP 429.
Credit cost
Each accepted signal costs 1 credit (third-party driver). Signals rejected due to rate limiting or deduplication are not charged.
What do the response codes mean?
| Code | Meaning |
|---|---|
| 200 | Signal received and dispatched |
| 400 | Invalid JSON object or missing/unrecognized direction; not dispatched or charged |
| 402 | Credits exhausted — strategy will not trade |
| 404 | Strategy not found or invalid secret |
| 429 | Rate limit exceeded |
| 502 | Engine dispatch failed |
How do I manage webhook secrets?
On the strategy detail page → TradingView panel:
- Generate — create a new secret (only if none exists)
- Rotate — replace the current secret with a new one; old secret is immediately invalid
- Delete — remove the secret and disable webhook reception for this strategy