tickerbot_subscribe_ticker
Push one ticker: we POST your endpoint whenever it matches the condition you give. Webhooks need a paid plan (Free has no webhook slots). Omit target_url for in-app delivery.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | WHERE-clause fragment using signal names from the schema — the same grammar as /v2/scan. (`condition` accepted as an alias.) | |
| dir | No | Sort direction for `order`. | desc |
| name | No | Human-readable label (up to 80 chars). Defaults to `<TICKER>: <query>`. | |
| order | No | 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). | market_cap |
| ticker | Yes | 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. | |
| cadence | No | 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`. | |
| channel | No | 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. | |
| columns | No | 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. | |
| condition | No | Original name for `q` — accepted as well. The same WHERE-clause fragment; send either spelling. | |
| device_id | No | Device to notify, from `POST /v2/devices/register`. Required when `channel` is `mobile_push`; unknown ids are a 404 `device_not_found`. | |
| target_url | No | https:// URL to POST when the condition fires. Omit for in-app delivery (visible in the dashboard). | |
| discord_url | No | 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | The stored predicate. Custom signals appear expanded: the SQL is frozen at creation. | |
| id | Yes | The webhook id — `wh_…`, the handle for every other call on this record. | |
| dir | Yes | Sort direction for that list; `null` means the default (`desc`). | |
| name | Yes | Your label for the subscription. | |
| as_of | Yes | Server time this response was assembled (ISO 8601). | |
| order | Yes | Sort signal for the payload row list; `null` means the evaluator default (`market_cap`). | |
| fields | Yes | Extra signals carried on each fired match row; `null` means the standard set. | |
| source | Yes | Which API version created the record; `v2` for anything you create today. | |
| status | Yes | `active` or `disabled`. Auto-disable follows repeated delivery failure. | |
| cadence | Yes | How often the trigger is evaluated — `realtime`, `hourly`, or `nyse_open`. | |
| channel | Yes | Where deliveries go: `webhook`, `discord`, `in_app`, or `mobile_push`. | |
| event_q | No | Event-trigger webhooks only: the payload filter, or `null`. | |
| rule_id | Yes | Legacy link to a v1 alert rule; `null` on everything created through v2. | |
| delivery | Yes | Legacy alias of `channel`, kept aligned for older readers. | |
| test_url | Yes | Returned on create only: the `POST /v2/webhooks/{id}/test` URL for this record. | |
| created_at | Yes | Creation timestamp. | |
| last_error | No | The last evaluation error; `null` on a healthy hook. The answer to "why is my webhook not firing?". | |
| last_fired | Yes | When a delivery last went out; `null` if it never has. | |
| target_url | Yes | Your HTTPS endpoint; `null` on every channel except `webhook`. | |
| updated_at | Yes | Last modification timestamp. | |
| event_kinds | No | Event-trigger webhooks only: the kinds subscribed (`split`, `dividend`, `insider`, `analyst`, `earnings`). | |
| universe_id | Yes | Universe the trigger is scoped to, or `null` for the whole market. | |
| next_eval_at | Yes | When the evaluator will next consider this subscription. | |
| trigger_kind | No | Event-trigger webhooks only: `event`. | |
| event_tickers | No | Event-trigger webhooks only: the symbols the trigger is scoped to, or `null` for the universe / whole market. | |
| channel_config | Yes | Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id). | |
| last_match_set | Yes | Tickers matching at the last evaluation — the set the next run is diffed against, which is what makes firing edge-triggered. | |
| signing_secret | Yes | Returned on create only — shown once, never again. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries. | |
| last_evaluated_at | Yes | When it was last evaluated; `null` until the first run. | |
| last_eval_error_at | No | When the last evaluation error happened; `null` on a healthy hook. | |
| subscription_origin | Yes | Which door created it — `type` (`ticker`/`signal`/`scan`/`event`), its `ref`, and the `condition` in display form. | |
| last_predicate_value | Yes | The trigger's value at the last evaluation; `null` until it has run. |