Subscribe to events
https://api.tickerbot.io/ v2/ events/ subscribeGets you an alert by webhook when new events of the kinds you choose land, filtered on the event and on the ticker's signals.
Body parameters
string[]enumrequiredEvent 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).
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). |
string[]One ticker or a comma list (up to 50). Not combinable with universe. Omit both for every ticker.
stringScope 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.
stringThe 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. See the signals catalog for columns + flags you can compose.
string[]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).
stringenumDelivery 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.
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. |
stringOnly with channel=webhook. HTTPS URL each delivery is POSTed to.
stringOnly 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.
stringOnly with channel=mobile_push. Device to notify, from POST /v2/devices/register. An unknown id is a 400 device_not_found.
stringDisplay name, up to 80 characters. Defaults to events: <kinds> · <scope>.
Headers
stringOptional unique string (≤255 chars). A retry carrying the same key within 24h replays the original response (Idempotency-Replayed: true header) instead of creating a duplicate; a concurrent duplicate gets 409 idempotency_in_flight; reusing a key for a different request (another method or path, or the same path with a different body) gets 422 idempotency_key_reused. Only a 2xx is stored: after a 4xx or 5xx, a retry with the same key runs again.
Returns
as_ofstringServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
idstringThe webhook id (wh_…), the handle for every other call on this record.
namestringYour label for the subscription.
qstringThe 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.
selectstring[]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.
orderstringSort 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.
dirstringenumSort direction for those lists: desc unless you chose one. null on event and news webhooks.
asc | Ascending: smallest or earliest first. |
desc | Descending: largest or most recent first. |
universestringUniverse the trigger is scoped to, or null for the whole market.
cadencestringenumScan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land.
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. |
channelstringenumWhere deliveries go.
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. |
target_urlstringYour HTTPS endpoint; null on every channel except webhook.
statusstringenumWhether it is live. disabled_reason says why a webhook is disabled.
active | The subscription is live and being evaluated. |
disabled | Turned off; disabled_reason says why. user_disabled: you turned it off. delivery_failure: deliveries kept failing for 72 hours with none getting through. evaluation_failure: its rule can no longer run, such as when a signal it reads was removed or its universe was deleted. plan_downgrade: the account moved to a plan with fewer webhooks, and the newest beyond the new limit were turned off. subscription_canceled: the paid subscription ended. Turn it back on with PATCH /v2/webhooks/{webhook} and enabled: true. |
subscription_originobjectWhich subscribe route created it: type (ticker/signal/scan/event/news), its ref and the condition in display form.
created_atnumberCreation timestamp (epoch seconds).
updated_atnumberLast modification timestamp (epoch seconds).
last_firednumberWhen a delivery last went out (epoch seconds); null if it never has.
last_match_setarrayScan, 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.
last_eval_error_atnumberWhen the last evaluation error happened (epoch seconds); null on a healthy hook.
last_errorstringThe last evaluation error; null on a healthy hook. The answer to "why is my webhook not firing?".
next_eval_atnumberWhen the evaluator will next consider this subscription (epoch seconds).
last_evaluated_atnumberScan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); null until the first run.
kindstring[]enumEvent webhooks only: the kinds subscribed.
earnings | Fires on each quarterly earnings report: reported vs estimated EPS and the surprise. |
filing | Fires when a 10-K, 20-F, 40-F or 10-Q lands, from the next morning’s EDGAR index read. |
dividend | Fires on each cash-dividend declaration. |
split | Fires on each stock split or reverse split. |
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). |
tickerarrayEvent and news webhooks only: the symbols it is scoped to, or null for the universe or the whole market.
searchstringNews webhooks only: the full-text search it fires on, or null.
min_relevancenumberNews webhooks only: the least relevance a scoped ticker needs, or null.
consecutive_failuresnumberDeliveries 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.
last_success_atnumberWhen a delivery last reached your endpoint, in epoch seconds (created_at until the first one does).
failing_sincenumberWhen the current failure streak began (epoch seconds); null while deliveries are succeeding.
channel_config_presentbooleanDiscord and mobile-push webhooks: true when delivery settings are stored. The Discord URL itself is never returned after create.
disabled_reasonstringenumDisabled webhooks only: why it was turned off. Turn it back on with PATCH /v2/webhooks/{webhook} and enabled: true.
user_disabled | You turned it off. |
delivery_failure | Deliveries kept failing for 72 hours with none getting through. |
evaluation_failure | Its rule can no longer run, for example because a signal it names was renamed or its universe was deleted. disabled_explanation says what changed. |
plan_downgrade | Your webhook limit went down, and the newest webhooks over the new limit were turned off. |
subscription_canceled | Your paid subscription ended. |
disabled_last_status_codenumberAfter a delivery_failure: the HTTP status your endpoint last returned.
disabled_last_errorstringAfter 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).
disabled_explanationstringAfter an evaluation_failure: what changed and what to use instead, for example the new name of a renamed signal.
disabled_atnumberAfter an evaluation_failure, plan_downgrade or subscription_canceled: when it was disabled (epoch seconds).
disable_email_sent_atnumberWhen we emailed you about the disable (epoch seconds).
channel_configobjectReturned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).
signing_secretstringReturned on create only, and shown once. HMAC key for verifying the X-Tickerbot-Signature header on deliveries.
test_urlstringReturned on create only, when the channel delivers outside the dashboard: the path of POST /v2/webhooks/{webhook}/test for this record.
_metaobjectReturned 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.
Status codes
| Code | Meaning |
|---|---|
201 | Webhook subscription created: the same shape as GET /v2/webhooks/{webhook}, plus test_url (channels that deliver outside the dashboard) and, on create only, signing_secret (shown once, for HMAC verification) and channel_config (the Discord URL or device id you sent). Later reads drop signing_secret and the Discord URL. |
400 | bad_request: missing or unknown kind, >50 tickers, any of the tickers not ones we track, some or all (the message names them), a crypto, FX or rate ticker (these kinds are equities-only; the message points at Subscribe to a ticker or Subscribe to a scan for its signals), ticker+universe together, an invalid q, or an expression in select (names only). cadence, order and dir are a 400 (unknown_parameter): an event is delivered when it lands. So is a channel value outside its list, channel: "webhook" without target_url, or a destination field for another channel (target_url with channel: "in_app"). asof, grain, group_by, having, limit and cursor are a 400 naming why. universe_not_found: an unknown universe; device_not_found: an unknown device_id (each named). |
403 | webhook_tier_required (Free) or webhook_limit_reached (at cap): event webhooks use the same plan slots. |
409 | idempotency_in_flight: a concurrent request carried the same Idempotency-Key. |
422 | idempotency_key_reused: the Idempotency-Key was already used for a different request. |
Notes
- Creates a webhook; list, update and delete it at
/v2/webhooks. - Latency is each kind's freshness (Query events lists it), not sub-minute: only genuinely new events fire.
- Only events that land after you subscribe fire, and only events from the last 7 days. Call the returned
test_urlto send a sample delivery (the same shape, headers and signature as a real fire, with one sample event) and check your receiver. - Delivery payloads use
event: "events.fired"with aneventsarray of{ id, ticker, ts, kind, payload }results (or theselectkeys), the same shapes Query events serves, up to 2,000 per delivery (events_truncated: truebeyond that);event_countis how many events matched (more thaneventsholds when it is truncated), andidtells a re-delivered event from a new one. Receivers handling several webhook types should branch on theeventfield.