Subscribe to news
https://api.tickerbot.io/ v2/ news/ subscribeGets you an alert by webhook when a new article matches your search, tickers or SQL filter, with how it treats each ticker it mentions.
Body parameters
stringFull-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.
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. Articles that mention any member fire.
numberOnly with ticker or universe. Only articles about one of the tickers (its relevance at least this value, 0 to 1).
stringThe 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.
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 news: <scope> · <search or q>.
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: 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). |
403 | webhook_tier_required (Free) or webhook_limit_reached (at cap): news 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. - 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_urlto 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"witharticles, each the article row as Query news returns it (or theselectfields) plusidandmentions, oldest first, up to 100 per delivery;article_countis how many this delivery carries. The payload also echoessearch,ticker,universeandq. Receivers handling several webhook types should branch on theeventfield.