View as markdown
Endpoints · Events

Subscribe to events

POSThttps://api.tickerbot.io/v2/events/subscribe

Creates an event-trigger webhook: it fires when NEW events of the chosen kinds land in the archives — "every split in my universe", "Goldman downgrades on tickers I hold" — with no polling on your side. Sugar for [POST /v2/webhooks](/docs/endpoints/webhooks/create) with trigger: { type: "event", … }; the webhook is listed/updated/deleted at /v2/webhooks like any other.

Two optional, composable filters — they answer different questions about different objects:

  • `q` filters the event's TICKER STATE at fire time — "downgrades, but only where market_cap > 1e10". Scan grammar; custom signals expand and freeze at creation.
  • `event_q` filters the EVENT CONTENT — "only where payload->>'firm' = 'Goldman Sachs'". The [GET /v2/events](/docs/endpoints/events) grammar over exactly (ticker, ts, kind, payload).

Deliveries carry event: "events.fired" with an events array of { ticker, ts, kind, payload } rows (same shapes as [GET /v2/events](/docs/endpoints/events)).

Latency is ingest cadence, not sub-minute: analyst actions ≤1 hour (the archive refreshes hourly, 24/7); dividend/split/insider kinds refresh daily in the evening ET pipeline. Only genuinely new events fire — historical backfills never do.

Plan access

Paid plans (Hobby and above).

Cadence

Real-time on every paid plan — evaluated on every data refresh (~1×/min), so a match is delivered within seconds of it landing. Optionally throttle a webhook to hourly or at-market-open.

Capacity

Hobby 10 · Pro 100 · Scale 1,000 · Enterprise unlimited.

Body parameters

stringrequired

Event kinds to fire on — array or comma list.

string

Scope to specific tickers (max 50). Mutually exclusive with `universe`. Omit both for all tickers.

string

Scope to a universe slug (`top_10`, `top_100`, or one of yours).

string

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. See the schema for columns + flags you can compose.

string

Optional event-CONTENT filter in the `/v2/events` grammar — only `ticker`, `ts`, `kind`, `payload` may appear. Composes with `q`.

string

HTTPS delivery URL; or use `channel` + `discord_url`/`device_id`. Omit for in-app.

string

Delivery channel.

string

Display name. Defaults to `events: <kinds> · <scope>`.

Status codes

201
The created webhook record + test_url.
400
bad_request — missing/unknown kinds, >50 tickers, tickers+universe together, or invalid q.
403
webhook_tier_required (Free) or webhook_limit_reached (at cap) — event webhooks consume the same plan slots.
404
Referenced universe does not exist.

Notes

  • Delivery payloads use event: "events.fired" (not webhook.fired) with an events array — receivers handling both webhook types should branch on the event field.