tickerbot_subscribe_events
Push new events: we POST your endpoint when events of the kinds you chose land in the archives. Webhooks need a paid plan (Free has no webhook slots). q filters the ticker STATE; event_q filters the EVENT payload in the /v2/events grammar. Latency is the ingest cadence (analyst ≤1h, corporate kinds daily), not sub-minute.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional row-STATE filter evaluated against the event's ticker at fire time. Same grammar as scan `q`; custom signals are expanded and frozen at creation. | |
| name | No | Display name. Defaults to `events: <kinds> · <scope>`. | |
| kinds | Yes | Event kinds to fire on — array or comma list. | |
| ticker | No | Single-symbol shorthand for `tickers`. | |
| channel | No | Delivery channel. `slack` is reserved and returns `501`. | |
| event_q | No | Optional event-CONTENT filter in the `/v2/events` grammar — only `ticker`, `ts`, `kind`, `payload` may appear. Composes with `q`. | |
| tickers | No | Scope to specific tickers (max 50). Mutually exclusive with `universe` — and with the singular alias `ticker` (sending both is a 400). Omit both for all tickers. | |
| universe | No | Scope to a universe slug (`top_10`, `top_100`, or one of yours). `universe_id` accepted as an alias. | |
| 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 delivery URL; or use `channel` + `discord_url`/`device_id`. Omit for in-app. | |
| 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. |