Subscribe to a ticker

POSThttps://api.tickerbot.io/v2/tickers/{ticker}/subscribe

Push one ticker: we POST your endpoint whenever it matches the condition you give.

Body parameters

tickerstringrequired

Case-insensitive. Equities are bare symbols (AAPL); every other class carries a prefix — rates (R:SOFR), crypto (X:BTCUSD), fx (X:EURUSD). Bare BTC/ETH are US-listed ETFs, not spot crypto. See Tickers.

qstringrequired

WHERE-clause fragment using signal names from the schema — the same grammar as /v2/scan. (condition accepted as an alias.) See the signals catalog for columns + flags you can compose.

conditionstring

Original name for q — accepted as well. The same WHERE-clause fragment; send either spelling.

target_urlstring

https:// URL to POST when the condition fires. Omit for in-app delivery (visible in the dashboard).

channelenum

Delivery channel. webhook (POST to target_url), discord (post an embed to discord_url), in_app (dashboard only), or mobile_push (notify a phone signed in to the Tickerbot mobile app; requires a device_id from POST /v2/devices/register). Inferred when omitted: webhook if target_url is set, discord if discord_url is set, else in_app. slack is reserved and returns 501. See the Delivery channels guide.

`webhook`	POST the payload to an HTTPS endpoint you own, signed with `X-Tickerbot-Signature`.
`discord`	Post to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed — the URL is itself the credential.
`in_app`	Deliver to the in-app feed. No external receiver, so nothing to validate and no `test_url`.
`mobile_push`	Push to a registered device. Requires a `device_id` from Register a device.

discord_urlstring

Discord incoming-webhook URL (https://discord.com/api/webhooks/…). Required when channel is discord. Stored as a posting credential: the create response echoes it back under channel_config, but every later read (list, get, deliveries) strips it and sets channel_config_present: true instead.

device_idstring

Device to notify, from POST /v2/devices/register. Required when channel is mobile_push; unknown ids are a 404 device_not_found.

cadenceenum

How often to evaluate. realtime (the default) is evaluated on every data refresh (~1×/min); hourly and nyse_open throttle to a batch schedule. 1m is a deprecated alias for realtime.

`realtime`	Evaluate on every refresh — the canonical value. (`1m` is a deprecated alias that collapses to this.)
`hourly`	Batch schedule: evaluate once an hour.
`nyse_open`	Batch schedule: evaluate once per session, at the NYSE open.

namestring

Human-readable label (up to 80 chars). Defaults to <TICKER>: <query>.

columnsstring[]

Comma-separated extra signals to include in each fired payload match row, beyond the standard set (ticker, name, asset_type, price, change_1d_pct, market_cap). Each must be a real signal; an unknown signal is rejected at creation. fields accepted as an alias — and note the RESPONSE reports them under fields, as an array.

orderstringdefault market_cap

Signal the fired payload's match lists are sorted by before the 100-row cap is applied, so a truncated list is the deterministic top 100 rather than an arbitrary sample. Must be a real signal (validated at creation).

direnumdefault desc

Sort direction for order.

`asc`	Ascending — smallest or earliest first.
`desc`default	Descending — largest or most recent first.

Headers

Idempotency-Keystring

Optional unique string (≤255 chars). A retry carrying the same key within 24h replays the original response (Idempotency-Replayed: true header) instead of creating a duplicate; a concurrent duplicate gets 409 idempotency_in_flight; reusing a key for a *different* request (another method or path) gets 422 idempotency_key_reused. 5xx responses are not stored — those retries re-execute.

Returns

as_ofstring

Server time this response was assembled (ISO 8601).

idstring

The webhook id — `wh_…`, the handle for every other call on this record.

namestring

Your label for the subscription.

qstring

The stored predicate. Custom signals appear expanded: the SQL is frozen at creation.

rule_idstring

Legacy link to a v1 alert rule; `null` on everything created through v2.

fieldsstring

Extra signals carried on each fired match row; `null` means the standard set.

orderstring

Sort signal for the payload row list; `null` means the evaluator default (`market_cap`).

dirstring

Sort direction for that list; `null` means the default (`desc`).

universe_idstring

Universe the trigger is scoped to, or `null` for the whole market.

cadencestring

How often the trigger is evaluated — `realtime`, `hourly`, or `nyse_open`.

channelstring

Where deliveries go: `webhook`, `discord`, `in_app`, or `mobile_push`.

target_urlstring

Your HTTPS endpoint; `null` on every channel except `webhook`.

deliverystring

Legacy alias of `channel`, kept aligned for older readers.

statusstring

`active` or `disabled`. Auto-disable follows repeated delivery failure.

sourcestring

Which API version created the record; `v2` for anything you create today.

subscription_originobject

Which door created it — `type` (`ticker`/`signal`/`scan`/`event`), its `ref`, and the `condition` in display form.

last_predicate_valuestring

The trigger's value at the last evaluation; `null` until it has run.

created_atnumber

Creation timestamp.

updated_atnumber

Last modification timestamp.

last_firednumber

When a delivery last went out; `null` if it never has.

last_match_setarray

Tickers matching at the last evaluation — the set the next run is diffed against, which is what makes firing edge-triggered.

last_eval_error_atnumber

When the last evaluation error happened; `null` on a healthy hook.

last_errorstring

The last evaluation error; `null` on a healthy hook. The answer to "why is my webhook not firing?".

next_eval_atnumber

When the evaluator will next consider this subscription.

last_evaluated_atnumber

When it was last evaluated; `null` until the first run.

event_kindsarray

Event-trigger webhooks only: the kinds subscribed (`split`, `dividend`, `insider`, `analyst`, `earnings`).

event_qstring

Event-trigger webhooks only: the payload filter, or `null`.

event_tickersarray

Event-trigger webhooks only: the symbols the trigger is scoped to, or `null` for the universe / whole market.

trigger_kindstring

Event-trigger webhooks only: `event`.

channel_configobject

Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).

signing_secretstring

Returned on create only — shown once, never again. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries.

test_urlstring

Returned on create only: the `POST /v2/webhooks/{id}/test` URL for this record.

_metaobject

Returned on create only, and only when the rule or `columns` named a column under its pre-2026-09-07 spelling: `deprecated_columns` lists each one (`requested`, `use`, `note`). The stored rule carries the current name.

Status codes

201

Webhook subscription created — the same shape as GET /v2/webhooks/{id}, plus test_url and, uniquely on create, signing_secret (shown once, for HMAC verification) and the raw channel_config you supplied. Later reads strip both.

400

bad_request — missing q, invalid ticker, or malformed target_url.

403

webhook_tier_required or webhook_limit_reached.

404

not_found — ticker is not tracked; device_not_found — unknown device_id.

409

idempotency_in_flight — a concurrent request carried the same Idempotency-Key.

422

idempotency_key_reused — the Idempotency-Key was already used for a different request.

501

channel_not_implemented — channel: "slack" is reserved.

Notes

Shorthand for POST /v2/webhooks with a { type: "ticker" } trigger — one of the four doors to the same webhook object, listed, updated, and deleted at /v2/webhooks. It counts against your account-wide webhook cap.
The predicate is scoped to the path ticker automatically, so do not add ticker = '…' yourself. (condition, the original name, is still accepted.)
Returns the same shape as GET /v2/webhooks/{id}, plus a test_url for wire-delivered channels (webhook, discord). Subscribing does NOT auto-fire anything at your endpoint — hit the test URL to send a real-shape webhook.fired and validate your receiver. In-app subscriptions have no external receiver and carry no test_url.
Custom signals referenced in the predicate are expanded and frozen into the webhook at creation. Editing the signal later does not change this subscription — re-subscribe to apply.

More examples

Deliver to Discord instead of an HTTPS endpoint

curl -X POST "https://api.tickerbot.io/v2/tickers/NVDA/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"rsi_oversold AND high_volume_alert","channel":"discord","discord_url":"https://discord.com/api/webhooks/123456789012345678/aBcDeF…","cadence":"realtime"}'

Response

{
  "as_of": "2026-07-27T16:41:00.000Z",
  "id": "wh_dC9rTq-k77p",
  "name": "NVDA: rsi_oversold AND high_volume_alert",
  "q": "ticker = 'NVDA' AND (rsi_oversold AND high_volume_alert)",
  "cadence": "realtime",
  "target_url": null,
  "channel": "discord",
  "delivery": "discord",
  "channel_config": {
    "url": "https://discord.com/api/webhooks/123456789012345678/aBcDeF…"
  },
  "signing_secret": "whsec_…",
  "status": "active",
  "subscription_origin": {
    "type": "ticker",
    "ref": "NVDA",
    "condition": "rsi_oversold AND high_volume_alert"
  },
  "test_url": "/v2/webhooks/wh_dC9rTq-k77p/test",
  "created_at": 1785170460
}

curl -X POST "https://api.tickerbot.io/v2/tickers/NVDA/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "rsi_oversold AND high_volume_alert",
    "target_url": "https://example.com/hook",
    "name": "NVDA oversold",
    "columns": [
      "rsi_14",
      "macd_line"
    ],
    "order": "market_cap",
    "dir": "desc"
  }'

Sample response

{
  "as_of": "2026-07-27T16:40:00.000Z",
  "id": "wh_smRsF3-z36o",
  "name": "NVDA: rsi_oversold AND high_volume_alert",
  "q": "ticker = 'NVDA' AND (rsi_oversold AND high_volume_alert)",
  "rule_id": null,
  "fields": null,
  "order": null,
  "dir": null,
  "universe_id": null,
  "cadence": "realtime",
  "channel": "webhook",
  "target_url": "https://example.com/hook",
  "delivery": "webhook",
  "signing_secret": "whsec_…",
  "status": "active",
  "source": "v2",
  "subscription_origin": {
    "type": "ticker",
    "ref": "NVDA",
    "condition": "rsi_oversold AND high_volume_alert"
  },
  "test_url": "/v2/webhooks/wh_smRsF3-z36o/test",
  "created_at": 1785170400,
  "updated_at": 1785170400,
  "...": "(evaluator bookkeeping fields)"
}