tickerbot_subscribe_ticker
Creates an alert that fires when a single ticker starts matching a condition, delivered via webhook, Discord, mobile push, or in-app feed on realtime, hourly, or NYSE-open cadence.
Instructions
Gets you an alert by webhook each time one ticker starts matching a condition. Webhooks need a paid plan (Free has no webhook slots). Omit target_url for in-app delivery.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | WHERE-clause fragment using signal names from the catalog, the same grammar as `/v2/scan`. Custom signals are expanded and frozen in at creation. | |
| name | No | Display name, up to 80 characters. Defaults to `<TICKER>: ` plus the first 40 characters of `q`. | |
| select | No | What each delivery carries. Omitted: the scan default row (ticker, name, asset_class, asset_type, price, change_1d_pct, gap_pct, relative_volume, market_cap) plus every signal used in `q`. A list of signal names: exactly those, `ticker` always included. Each must be a real signal; unknown ones are rejected at creation. `*` and expressions are a 400: a delivery lists up to 100 matches, so name the signals. | |
| ticker | Yes | One ticker. For several, use Subscribe to a scan with `q="ticker IN ('NVDA','AAPL') AND (…)"`. Case-insensitive. Equities are bare symbols (`NVDA`); 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 checked each time the data refreshes, about once a minute; `hourly` and `nyse_open` are checked on that schedule. Values: realtime: Checked each time the data refreshes: about once a minute from 4 AM to 8 PM ET for stocks and ETFs, every minute around the clock for crypto and FX, and as each event lands for event webhooks. Fires when a ticker starts matching. The default. hourly: Checked once an hour. nyse_open: Checked once a day, at the 9:30 AM ET open, on NYSE trading days. | |
| channel | No | Delivery channel: `webhook` (POST to `target_url`), `discord` (an embed at `discord_url`), `in_app` (the dashboard only) or `mobile_push` (to `device_id`). Inferred when omitted: `discord` if `discord_url` is set, else `mobile_push` if `device_id` is set, else `webhook` if `target_url` is set, else `in_app`. See Delivery channels. Values: 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. | |
| device_id | No | Only with `channel=mobile_push`. Device to notify, from `POST /v2/devices/register`. An unknown id is a 400 `device_not_found`. | |
| target_url | No | Only with `channel=webhook`. HTTPS URL each delivery is POSTed to. | |
| discord_url | No | Only with `channel=discord`. Discord incoming-webhook URL (`https://discord.com/api/webhooks/…`). 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
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | The stored predicate. Custom signals appear expanded: the SQL is frozen at creation. On an event webhook, the whole filter (the event's fields and the ticker's signals); `null` when it fires on every event. On a news webhook, the Query news `q`, or `null`. | |
| id | Yes | The webhook id (`wh_…`), the handle for every other call on this record. | |
| dir | Yes | Sort direction for those lists: `desc` unless you chose one. `null` on event and news webhooks. One of: `asc`, `desc`. | |
| kind | No | Event webhooks only: the kinds subscribed. One of: `earnings`, `filing`, `dividend`, `split`, `insider`, `analyst`, `estimate_revision`. | |
| name | Yes | Your label for the subscription. | |
| _meta | No | Returned on create only, and only when the rule or `select` named a signal under its pre-2026-09-07 spelling: `deprecated_signals` lists each one (`requested`, `use`, `note`). The stored rule carries the current name. | |
| as_of | Yes | Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of). | |
| order | Yes | Sort signal for each delivery's match lists: `market_cap` unless you chose one, so a broad alert lists the same top 100 names each time. `null` on event and news webhooks. | |
| search | No | News webhooks only: the full-text search it fires on, or `null`. | |
| select | Yes | The signals each delivered match carries, after `ticker`; `null` means the scan default row plus the signals the rule uses in `q` and `order`. On a news webhook, the article fields each delivered article carries. | |
| status | Yes | Whether it is live. `disabled_reason` says why a webhook is disabled. One of: `active`, `disabled`. | |
| ticker | No | Event and news webhooks only: the symbols it is scoped to, or `null` for the universe or the whole market. | |
| cadence | No | Scan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land. One of: `realtime`, `hourly`, `nyse_open`. | |
| channel | Yes | Where deliveries go. One of: `webhook`, `discord`, `in_app`, `mobile_push`. | |
| test_url | No | Returned on create only, when the channel delivers outside the dashboard: the path of `POST /v2/webhooks/{webhook}/test` for this record. | |
| universe | Yes | Universe the trigger is scoped to, or `null` for the whole market. | |
| created_at | Yes | Creation timestamp (epoch seconds). | |
| 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 (epoch seconds); `null` if it never has. | |
| target_url | Yes | Your HTTPS endpoint; `null` on every channel except `webhook`. | |
| updated_at | Yes | Last modification timestamp (epoch seconds). | |
| _advisories | No | Present only when the response carried a warning: `deprecated` (since, sunset_on, successor, warning; on a deprecated tool, successor names the tool to call), `rate_limit` (warning, retry_after_seconds, limit, remaining, reset_epoch_s) or `monthly_quota` (warning, limit, remaining, reset_epoch_s). | |
| disabled_at | No | After an `evaluation_failure`, `plan_downgrade` or `subscription_canceled`: when it was disabled (epoch seconds). | |
| next_eval_at | No | When the evaluator will next consider this subscription (epoch seconds). | |
| failing_since | No | When the current failure streak began (epoch seconds); `null` while deliveries are succeeding. | |
| min_relevance | No | News webhooks only: the least `relevance` a scoped ticker needs, or `null`. | |
| 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 | No | Scan, ticker and signal webhooks only: 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, and shown once. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries. | |
| disabled_reason | No | Disabled webhooks only: why it was turned off. Turn it back on with `PATCH /v2/webhooks/{webhook}` and `enabled: true`. One of: `user_disabled`, `delivery_failure`, `evaluation_failure`, `plan_downgrade`, `subscription_canceled`. | |
| last_success_at | No | When a delivery last reached your endpoint, in epoch seconds (`created_at` until the first one does). | |
| last_evaluated_at | No | Scan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); `null` until the first run. | |
| last_eval_error_at | No | When the last evaluation error happened (epoch seconds); `null` on a healthy hook. | |
| disabled_last_error | No | After a `delivery_failure` or `evaluation_failure`: the error that disabled it; `null` when your endpoint answered with an HTTP status (see `disabled_last_status_code`). | |
| subscription_origin | Yes | Which subscribe route created it: `type` (`ticker`/`signal`/`scan`/`event`/`news`), its `ref` and the `condition` in display form. | |
| consecutive_failures | No | Deliveries in a row that failed after the full retry ladder; resets on any success. Informational: a webhook is disabled when deliveries have kept failing for 72 hours (since `failing_since`) with none getting through, not on a count. | |
| disabled_explanation | No | After an `evaluation_failure`: what changed and what to use instead, for example the new name of a renamed signal. | |
| disable_email_sent_at | No | When we emailed you about the disable (epoch seconds). | |
| channel_config_present | No | Discord and mobile-push webhooks: `true` when delivery settings are stored. The Discord URL itself is never returned after create. | |
| disabled_last_status_code | No | After a `delivery_failure`: the HTTP status your endpoint last returned. |