tickerbot.io

Subscribe to news

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

Gets you an alert by webhook when a new article matches your search, tickers or SQL filter, with how it treats each ticker it mentions.

string

Full-text search over title + summary, as on Query news.

string[]

One ticker or a comma list (up to 50): articles that mention any of them. Not combinable with universe.

string

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. Articles that mention any member fire.

number

Only with ticker or universe. Only articles about one of the tickers (its relevance at least this value, 0 to 1).

string

The filter, as on Query news: article fields and the per-mention fields ticker, relevance, sentiment_score and sentiment. An article fires once when any of its mentions matches. See the signals catalog for columns + flags you can compose.

string[]

The article fields each delivered article carries, besides id and mentions (always sent). Names only. Omitted: the Query news default row.

stringenum

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.

webhookPOST the payload to an HTTPS endpoint you own, signed with X-Tickerbot-Signature.
discordPost to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed: the URL is itself the credential.
in_appDeliver to the in-app feed. No external receiver, so nothing to validate and no test_url.
mobile_pushPush to a registered device. Requires a device_id from Register a device.
string

Only with channel=webhook. HTTPS URL each delivery is POSTed to.

string

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.

string

Only with channel=mobile_push. Device to notify, from POST /v2/devices/register. An unknown id is a 400 device_not_found.

string

Display name, up to 80 characters. Defaults to news: <scope> · <search or q>.

string

Optional 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.

as_ofstring

Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).

idstring

The webhook id (wh_…), the handle for every other call on this record.

namestring

Your label for the subscription.

qstring

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.

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.

orderstring

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.

dirstringenum

Sort direction for those lists: desc unless you chose one. null on event and news webhooks.

ascAscending: smallest or earliest first.
descDescending: largest or most recent first.
universestring

Universe the trigger is scoped to, or null for the whole market.

cadencestringenum

Scan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land.

realtimeChecked 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.
hourlyChecked once an hour.
nyse_openChecked once a day, at the 9:30 AM ET open, on NYSE trading days.
channelstringenum

Where deliveries go.

webhookPOST the payload to an HTTPS endpoint you own, signed with X-Tickerbot-Signature.
discordPost to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed: the URL is itself the credential.
in_appDeliver to the in-app feed. No external receiver, so nothing to validate and no test_url.
mobile_pushPush to a registered device. Requires a device_id from Register a device.
target_urlstring

Your HTTPS endpoint; null on every channel except webhook.

statusstringenum

Whether it is live. disabled_reason says why a webhook is disabled.

activeThe subscription is live and being evaluated.
disabledTurned 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_originobject

Which subscribe route created it: type (ticker/signal/scan/event/news), its ref and the condition in display form.

created_atnumber

Creation timestamp (epoch seconds).

updated_atnumber

Last modification timestamp (epoch seconds).

last_firednumber

When a delivery last went out (epoch seconds); null if it never has.

last_match_setarray

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.

last_eval_error_atnumber

When the last evaluation error happened (epoch seconds); null on a healthy hook.

last_errorstring

The last evaluation error; null on a healthy hook. The answer to "why is my webhook not firing?".

next_eval_atnumber

When the evaluator will next consider this subscription (epoch seconds).

last_evaluated_atnumber

Scan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); null until the first run.

kindstring[]enum

Event webhooks only: the kinds subscribed.

earningsFires on each quarterly earnings report: reported vs estimated EPS and the surprise.
filingFires when a 10-K, 20-F, 40-F or 10-Q lands, from the next morning’s EDGAR index read.
dividendFires on each cash-dividend declaration.
splitFires on each stock split or reverse split.
insiderFires on each reported Form 4 transaction by an officer or director.
analystFires on each upgrade, downgrade, initiation or price-target change.
estimate_revisionFires 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).
tickerarray

Event and news webhooks only: the symbols it is scoped to, or null for the universe or the whole market.

searchstring

News webhooks only: the full-text search it fires on, or null.

min_relevancenumber

News webhooks only: the least relevance a scoped ticker needs, or null.

consecutive_failuresnumber

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.

last_success_atnumber

When a delivery last reached your endpoint, in epoch seconds (created_at until the first one does).

failing_sincenumber

When the current failure streak began (epoch seconds); null while deliveries are succeeding.

channel_config_presentboolean

Discord and mobile-push webhooks: true when delivery settings are stored. The Discord URL itself is never returned after create.

disabled_reasonstringenum

Disabled webhooks only: why it was turned off. Turn it back on with PATCH /v2/webhooks/{webhook} and enabled: true.

user_disabledYou turned it off.
delivery_failureDeliveries kept failing for 72 hours with none getting through.
evaluation_failureIts 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_downgradeYour webhook limit went down, and the newest webhooks over the new limit were turned off.
subscription_canceledYour paid subscription ended.
disabled_last_status_codenumber

After a delivery_failure: the HTTP status your endpoint last returned.

disabled_last_errorstring

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).

disabled_explanationstring

After an evaluation_failure: what changed and what to use instead, for example the new name of a renamed signal.

disabled_atnumber

After an evaluation_failure, plan_downgrade or subscription_canceled: when it was disabled (epoch seconds).

disable_email_sent_atnumber

When we emailed you about the disable (epoch seconds).

channel_configobject

Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).

signing_secretstring

Returned on create only, and shown once. HMAC key for verifying the X-Tickerbot-Signature header on deliveries.

test_urlstring

Returned on create only, when the channel delivers outside the dashboard: the path of POST /v2/webhooks/{webhook}/test for this record.

_metaobject

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.

CodeMeaning
201Webhook 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.
400bad_request: none of search, ticker, universe or q (the whole market is about 6,000 articles a weekday), ticker with universe, more than 50 tickers, any of the tickers not ones we track, some or all (the message names them), an invalid q, or select naming an expression or a per-mention field. from, to, order, dir and cadence do not apply and are a 400 naming why, as are a channel value outside its list, channel: "webhook" without target_url and 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).
403webhook_tier_required (Free) or webhook_limit_reached (at cap): news webhooks use the same plan slots.
409idempotency_in_flight: a concurrent request carried the same Idempotency-Key.
422idempotency_key_reused: the Idempotency-Key was already used for a different request.
  • Creates a webhook; list, update and delete it at /v2/webhooks.
  • Fires as new articles land (new articles land within 15 minutes); each article fires once. Only articles published in the last two days fire, so a late backfill never floods you.
  • Only articles that land after you subscribe fire. Call the returned test_url to send a sample delivery (the same shape, headers and signature as a real fire, with one sample article) and check your receiver.
  • Delivery payloads use event: "news.fired" with articles, each the article row as Query news returns it (or the select fields) plus id and mentions, oldest first, up to 100 per delivery; article_count is how many this delivery carries. The payload also echoes search, ticker, universe and q. Receivers handling several webhook types should branch on the event field.