tickerbot_subscribe_events
Subscribe to selected market event kinds and receive alerts via webhook, Discord, in-app feed, or mobile push when event-field and ticker-signal filters match.
Instructions
Gets you an alert by webhook when new events of the kinds you choose land, filtered on the event and on the ticker's signals. Webhooks need a paid plan (Free has no webhook slots). One q covers the event's fields (with one kind, bare: firm = 'Goldman Sachs') and the ticker's signals at fire time (market_cap > 1e10); on a name clash (price, cik) the ticker signal wins; the event's own value is payload->>'price'. Latency is the ingest cadence (analyst ≤1h, corporate kinds daily), not sub-minute.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | The filter, as on Query events with `join=state`: the event's own fields (`id`, `ticker`, `ts`, `kind`, `payload`, and with one kind its payload fields by bare name) and the ticker's signals at fire time, in one WHERE clause. A payload field and a signal with the same name resolve to the signal, as on Query events: `price` on insider, `cik` on filing. Spell the event's own value `payload->>'price'`. Custom signals are expanded and frozen at creation. | |
| kind | No | Event kinds to fire on, an array or a comma list. `filing` fires when a 10-K, 20-F, 40-F or 10-Q lands (the next morning's EDGAR index read); `estimate_revision` when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market). Values: earnings: Fires on each quarterly earnings report: reported vs estimated EPS and the surprise. dividend: Fires on each cash-dividend declaration. split: Fires on each stock split or reverse split. filing: Fires when a 10-K, 20-F, 40-F or 10-Q lands, from the next morning’s EDGAR index read. insider: Fires on each reported Form 4 transaction by an officer or director. analyst: Fires on each upgrade, downgrade, initiation or price-target change. estimate_revision: Fires when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market). | |
| name | No | Display name, up to 80 characters. Defaults to `events: <kinds> · <scope>`. | |
| select | No | What each delivered event carries: `id`, `ticker`, `ts` and `kind` always, then the names you list, at the top level: `payload`, the payload fields of the one kind named, and ticker signals at fire time. Omitted: each event as on Query events (`payload` whole). | |
| ticker | No | One ticker or a comma list (up to 50). Not combinable with `universe`. Omit both for every ticker. | |
| 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. | |
| universe | No | Scope to a built-in universe (`top_10`, `top_100`) or one of your own, by id. An unknown one is a 400 `universe_not_found` naming it. | |
| 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. |