tickerbot_create_webhook
Canonical create: a webhook is a trigger plus a delivery. Trigger shapes: scan {type:"scan", q, universe?}; ticker {type:"ticker", ticker, condition}; signal {type:"signal", signal, ticker?, universe?, condition?}; event {type:"event", kinds, tickers?, universe?, event_q?}. The subscribe tools are flat sugar over exactly this. Webhooks need a paid plan (Free has no webhook slots).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Sort direction for `order`. Not accepted on `event` triggers (400). | desc |
| name | No | Display name, max 80 characters. Defaults to an auto-generated one from the trigger. | |
| 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, not an arbitrary sample. Same contract as `POST /v2/scan`. Not accepted on `event` triggers (they deliver one event at a time). | market_cap |
| cadence | No | Evaluation cadence — a user preference — never gated. Event triggers deliver on ingest — only `realtime` is accepted on them (400 otherwise). | realtime |
| channel | No | Delivery channel. See Delivery channels. | |
| columns | No | Extra columns echoed in fired payloads' match rows (`fields` accepted as an alias). Not accepted on `event` triggers (400) — event deliveries carry the event payload, not state rows. | |
| trigger | Yes | What fires the webhook. A discriminated object — `trigger.type` picks the shape, and the fields below belong inside it. Each shape is also available as a flat-params shortcut: `POST /v2/scan/subscribe`, `/v2/tickers/{t}/subscribe`, `/v2/signals/{s}/subscribe`, `/v2/events/subscribe`. | |
| device_id | No | Registered device id (channel `mobile_push`, see /v2/devices). | |
| target_url | No | HTTPS delivery URL (the `webhook` channel), max 1024 characters. Omit for in-app delivery, or use `channel` + `discord_url`/`device_id` for other channels. | |
| discord_url | No | Discord webhook URL (channel `discord`). |
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. |