tickerbot.io

Subscribe to a signal

POSThttps://api.tickerbot.io/v2/signals/{signal}/subscribe

Gets you an alert by webhook each time a ticker starts matching one signal, bounded by a condition the way Get a signal is.

stringrequired

A signal name: a built-in signal or one of your custom signals. An unknown name is a 404.

string

The bound, in Get a signal's grammar: required for every signal that is not yes/no, shaped by its type. numeric: >70, <30, !=0. timestamp: <YYYY-MM-DDTHH:MM:SSZ or >=YYYY-MM-DD. date: >=YYYY-MM-DD. string: =ETF or !=ETF. A yes/no or custom signal takes none; sending one is a 400.

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.

string[]

What each delivered match carries. Omitted: the scan default row plus the signal. A list of signal names: exactly those, ticker always included. * and expressions are a 400: a delivery lists up to 100 matches, so name the signals.

stringdefault market_cap

Signal each delivery's match lists are sorted by before the 100-result cap applies, so a broad alert lists the same top 100 each time. Must be a real signal (validated at creation).

stringenumdefault desc

Sort direction for order.

ascAscending: smallest or earliest first.
descdefaultDescending: largest or most recent first.
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.

stringenum

How often to evaluate: realtime (the default) is checked each time the data refreshes, about once a minute; hourly and nyse_open are checked on that schedule.

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

Display name, up to 80 characters. Defaults to the condition: golden_cross, or rsi_14 < 30.

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: a signal that is not yes/no without condition, a condition on a yes/no or custom signal, a condition whose shape does not match the signal's type, an object or list signal (it has no condition form; screen on it with Subscribe to a scan), q (not a parameter here), an invalid select, channel: "webhook" without target_url, a destination field for another channel (target_url with channel: "in_app"), or a param that does not apply to a live alert (asof, grain, group_by, having, limit, cursor). unknown_parameter: ticker (use Subscribe to a ticker). universe_not_found: an unknown universe; device_not_found: an unknown device_id (each named).
403webhook_tier_required or webhook_limit_reached.
404unknown_signal: the signal in the path does not exist.
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. It is the same webhook as a scan alert on <signal> or <signal> <condition>.
  • For a condition on more than one signal, use Subscribe to a scan; q is not a parameter here, and sending it is a 400 that says so. For one ticker, use Subscribe to a ticker.
  • A custom signal's expression is frozen into the webhook at creation, so later edits don't change it; subscribe again to apply them.
  • Only a match that starts after you subscribe fires: the first check records what already matches, and a delivery goes out when a ticker starts matching. Call the returned test_url to send a sample delivery and check your receiver.

Oversold RSI across the top 100

curl -X POST "https://api.tickerbot.io/v2/signals/rsi_14/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "condition": "<30",
    "universe": "top_100",
    "target_url": "https://example.com/hook"
  }'
Show responseHide response
Response
{
  "as_of": "2026-11-11T16:44:00.000Z",
  "id": "wh_r3Kd9v-x72a",
  "name": "rsi_14 < 30",
  "q": "rsi_14 < 30",
  "select": null,
  "order": "market_cap",
  "dir": "desc",
  "universe": "top_100",
  "cadence": "realtime",
  "channel": "webhook",
  "target_url": "https://example.com/hook",
  "signing_secret": "whsec_…",
  "status": "active",
  "subscription_origin": {
    "type": "signal",
    "ref": "rsi_14",
    "condition": "<30"
  },
  "created_at": 1794415440,
  "…": "(the rest of the webhook object)",
  "test_url": "/v2/webhooks/wh_r3Kd9v-x72a/test"
}