Outgoing Webhooks
Outgoing webhooks send each confirmed trade of a bot to an https URL you set. You choose the JSON body and the headers, so the same feature can feed a trading service that expects a particular format, a spreadsheet, a chat bot or your own server. An exchange or service that takes a custom JSON body (OKX's signal endpoints, for example) is a typical target. TradeStaq does not ship a ready-made integration for any one service: you write the body that service expects.
This is different from the webhook that triggers your bot. That one brings signals in. This one sends trades out.
Requirements
- A plan that includes signal forwarding. Creating or editing a destination on a plan without it is refused. If your plan is downgraded, entries stop being sent, exits are still sent (while the destination is on), and you can still see and delete your destinations.
- A URL that starts with
https://.
Setting it up
- Open the bot and go to its Signals & Notifications tab.
- In Outgoing webhooks, choose Add destination.
- Fill in the name, the URL, an optional JSON body, and optional headers, secrets and constants.
- Choose when it fires: when a position opens, when it closes, and whether paper trades are included.
- Use Preview to see the body, then Send test to try the URL.
A bot can have up to 5 destinations, and your account up to 20 in total. A new or re-enabled destination takes effect within a few seconds. A bot that copies another trader cannot use outgoing webhooks, because it would rebroadcast that trader's trades.
The body
The body is a JSON text with {{variable}} placeholders. Click a variable in the form to insert it.
- Inside quotes, a value is inserted as escaped text, so a bot name with a quote in it cannot break your JSON.
- Outside quotes, a number stays a number and an empty value becomes
null. Text is quoted for you. - A variable name that does not exist is rejected when you save.
{
"token": "{{secret.SIGNAL_TOKEN}}",
"action": "{{action}}",
"instrument": "{{instrument_id}}",
"price": {{price}},
"size": {{size}},
"strategy": "{{const.STRATEGY_LABEL}}"
}
This is the shape a service such as OKX's signal endpoints takes: a JSON body with a token in it. TradeStaq does not ship a ready-made integration for any service, so use the field names your service documents.
The token is a secret, not a constant: type it under Secrets (for the body) as SIGNAL_TOKEN, and it is put into the body when the request is sent. If your service instead wants the token in a header, use a header (for example X-Signal-Token).
Leave the body empty to send the default: one JSON object with every variable below as a field.
Variables
| Variable | Meaning |
|---|---|
{{action}} | enter_long, exit_long, enter_short or exit_short. |
{{side}} | long or short: the direction of the position the event is about (for an exit, the one that was closed). |
{{symbol}} | The market as TradeStaq shows it, for example BTC/USDT:USDT. |
{{base}} | The base asset, for example BTC. |
{{quote}} | The quote asset, for example USDT. |
{{instrument_id}} | The exchange's own market id when known (for example OKX BTC-USDT-SWAP); empty otherwise. |
{{price}} | The fill price. |
{{size}} | The amount filled or closed, in base units (the part actually booked, for a partial close). |
{{notional_usd}} | The size times the price, in USD, when known. |
{{stop}} | The position's stop-loss price when it has one. |
{{take_profit}} | The position's take-profit price when it has one. |
{{pnl}} | Net realized profit or loss in USD. Exits only; empty on an entry. |
{{reason}} | Why an exit happened, for example stop_loss, take_profit, signal or manual. Empty on an entry. |
{{bot_name}} | The bot's name. |
{{strategy}} | The strategy's name, when the bot runs one. |
{{bot_id}} | The bot's id. |
{{event_id}} | A unique id for this event. The same event is never sent twice with different ids. |
{{timestamp}} | When the fill happened, as an ISO 8601 UTC time. |
{{timestamp_ms}} | The same moment in milliseconds since 1970. |
{{is_paper}} | true for a paper-trading event, false for a live one. |
{{price_known}} | true when the event has a price; false for an exit booked without a readable price (then price is empty or null). |
{{source}} | What caused the trade: strategy, signal, manual, reconcile, bot_deleted or other. |
{{const.NAME}} | A constant you defined on the destination (see below). |
Headers
Add up to 10 headers, for example Authorization or an API key header.
- Header values are encrypted when stored and are never shown again. After saving, the form shows only the last four characters. Leave a saved value empty when editing to keep it, or type a new one to replace it.
- Names use letters, digits and hyphens. Each value can be up to 1000 characters.
- Header values belong to the host you saved them for. If you change the URL to a different host, you must type every header value again; saved values are never carried over to a new host.
- TradeStaq sets
Content-Type: application/jsonandUser-Agent: TradeStaq-Webhook/1itself, andHost,Content-Length,ConnectionandTransfer-Encodingcannot be changed.
Secrets
Secrets are values you need inside the body, such as a token a service wants as a JSON field. Use them as {{secret.NAME}}.
- Names use capital letters, digits and underscores, starting with a letter (up to 40 characters). You can add up to 10, each up to 500 characters.
- Values are encrypted when stored and are never shown again. After saving, the form shows only a short hint. Leave a saved value empty when editing to keep it, or type a new one to replace it.
- Like headers, secrets belong to the host you saved them for: if you change the URL to a different host, type every header and every secret again.
- Preview shows a secret as
••••. Preview never decrypts a secret and never sends anything.
Constants
Constants are fixed values you reuse in the body as {{const.NAME}}: a label or an identifier your service asks for in the body, say. They are for non-secret text. Names use letters, digits and underscores (up to 40 characters), values are up to 500 characters, and you can add up to 20.
Constants are not secret. They are stored as plain text and shown in plain text to anyone who can see the bot's settings. Put every token, key or password in a header or a secret, whose value is encrypted and never shown again.
When events fire
An event is sent only for a confirmed fill:
- Open: when a position is open on a confirmed fill. A market entry fires once the order is booked; a limit entry fires when it fills. An order that was placed but not filled, or was canceled, sends nothing.
- Close: when a close is booked. That includes exits from your strategy or signal, stop losses, take profits, closes caused by a reconcile, manual closes and closes made when a bot is deleted. A partial close sends the part that closed.
- Not sent: positions that TradeStaq adopts from your exchange, failed orders, and internal bookkeeping that opens no new exposure.
- Paper trades are off by default. Turn on Include paper trades on the destination to send them;
is_papertells your service which is which.
Each event has a unique event_id. Events are delivered at least once: a retry after a lost answer can deliver the same event again, so your receiver should ignore an event_id it has already handled. Every delivery also carries these headers: X-TradeStaq-Event-Id (the same id), X-TradeStaq-Delivery-Attempt (1 for the first try) and User-Agent: TradeStaq-Webhook/1.
- An entry older than 5 minutes when it would be sent, or whose position is already closed, is dropped. An exit older than 45 minutes is dropped.
- Exits are sent for any position of the bot, including one opened before the webhook existed, and one opened while the open or paper switches were off. Your receiver should ignore an exit for a position it does not hold.
- Exits are sent whatever your plan says, while the destination is enabled and its close and paper switches are on; an exit older than 45 minutes is dropped. Entries stop when the plan no longer includes the feature.
- You are alerted once when a destination turns itself off.
A later event waits up to 3 minutes for an earlier one that is still being retried; after that it is sent anyway, so use timestamp or event_id if order matters. An exit is sent when TradeStaq books it. If the exit price could not be read, it is sent with an empty price (null outside quotes, empty text inside quotes) rather than a guessed one.
Delivery and retries
- A response with a 2xx status counts as delivered.
- Network errors, timeouts, 5xx, 408 and 429 are retried, up to 8 attempts in total (about 20 minutes), with waits that double each time starting at 10 seconds. Redirects, other 4xx answers and blocked addresses fail at once and are not retried.
- A request waits up to 8 seconds for an answer, and TradeStaq reads at most the first 2 KB of the response.
- A destination sends at most 120 entries and 600 exits a minute, and your account at most 300 entries a minute across all its destinations. Events beyond that are dropped and logged as rate limited.
- After 20 failed events in a row, the destination is turned off and shows why. Fix the problem, then switch it back on: that clears the failure count.
The Delivery log on each destination shows its last 50 attempts for 14 days: time, result, HTTP status, duration and a short error or response excerpt. It never contains your header values.
Security
- https only, port 443 only. A URL with a username or password in it is refused.
- Private addresses are blocked. Addresses on your own network, loopback, link-local and other internal ranges are refused, checked again when the request connects, so a hostname that changes after saving cannot reach them.
- Redirects are not followed.
- TradeStaq's own addresses are refused, so a bot cannot send its trades into a TradeStaq webhook. TradeStaq's inbound webhooks also reject any request that carries the headers above.
- Header values are encrypted at rest and never returned by TradeStaq.
Preview and Send test
Preview renders your body with sample values and lists the header names that would be sent. It also renders the body for an exit TradeStaq could not price, and warns when that body would be invalid JSON or would send null where a price is expected. Nothing is sent.
Send test makes a real request to your URL with a sample event. TradeStaq does not mark it as a test, because many services reject unknown fields. If the URL belongs to a trading service, it may act on the sample, so use a sandbox or a demo endpoint if the service offers one. You are asked to confirm before it is sent, and each destination allows 5 test sends an hour.
Troubleshooting
| Symptom | Check |
|---|---|
| Save is refused | The message names the problem: an unknown variable, invalid JSON once variables are filled in, a blocked header or a bad URL. |
| Nothing arrives | Is the destination on? Is the matching switch (open, close, paper) on? Look at the Delivery log. |
| Turned off by itself | 20 events in a row failed. Read the last error in the log, fix it, switch it back on. |
| HTTP 4xx in the log | Your service refused the request: check the body format and the headers. |
| Rate limited | More than 120 entries or 600 exits in a minute went to this destination, or more than 300 entries in a minute across your destinations. |