tickerbot_subscribe_scan
Push a whole query: we POST your endpoint every time the match set changes. Webhooks need a paid plan (Free has no webhook slots). Use for "alert me when this happens" requests.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | WHERE-clause expression using signal names — the same grammar and the same 4000-char cap as `POST /v2/scan`, so anything scannable is subscribable. Custom signals are expanded and frozen in at creation. | |
| dir | No | Sort direction for `order`. | desc |
| name | No | Human-readable label (up to 80 chars). Defaults to `scan: <q>`. | |
| order | No | Signal the payload's match lists are sorted by before the 100-row cap applies, so a truncated list is the deterministic top 100 rather than an arbitrary sample. Must be a real signal (validated at creation). | market_cap |
| cadence | No | `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` (embed to `discord_url`), `in_app` (dashboard only), or `mobile_push` (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`. | |
| columns | No | Extra signals per fired payload match row, beyond the standard set (`ticker`, `name`, `asset_type`, `price`, `change_1d_pct`, `market_cap`). Each must be a real signal; unknown ones are rejected at creation. `fields` accepted as an alias — and the RESPONSE reports them under `fields`, as an array. | |
| universe | No | System or user-owned universe to scope the scan. `universe_id` accepted as an alias. Unknown universes are a 404 `universe_not_found`. | |
| 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 match set changes. Omit for in-app delivery. | |
| discord_url | No | Discord incoming-webhook URL. 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. |