Update a webhook
https://api.tickerbot.io/ v2/ webhooks/ {webhook}Edits a webhook in place; send only the fields you want to change.
Path parameters
stringrequiredWebhook id.
Body parameters
stringOnly with news webhooks. The full-text search, as on Subscribe to news.
string[]enumOnly with event webhooks. The kinds to fire on, as on Subscribe to events.
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). |
stringOnly with signal webhooks. The bound, in Get a signal's grammar (<30).
string[]Only with event or news webhooks. The symbols, one or a comma list. Replaces a universe scope.
stringOnly with scan, signal, event or news webhooks. The universe to scope to; null for the whole market. On event and news webhooks it replaces a ticker scope.
numberOnly with news webhooks. The least relevance (0–1) a scoped ticker needs; the webhook needs a ticker or universe scope.
stringOnly with scan, ticker, event or news webhooks. The filter, in the grammar of the subscribe that made the webhook. On an event webhook it replaces the whole filter. On a ticker webhook send the condition alone, or the q a read returns (ticker = 'NVDA' AND (…)): the webhook's own ticker scope is not added twice. A change to the filters (q, condition, universe, kind, ticker, search, min_relevance) fires only on new matches; an edit of select, order or dir keeps what already matched. See the signals catalog for columns + flags you can compose.
string[]What each delivery carries, as on the subscribe that made the webhook; null for the default.
stringOnly with scan or signal webhooks. The signal each delivery's match lists are sorted by.
stringenumOnly with scan or signal webhooks. The sort direction for order.
asc | Ascending: smallest or earliest first. |
desc | Descending: largest or most recent first. |
stringenumMoves the webhook to another channel: webhook (with target_url), discord (with discord_url), in_app or mobile_push (with device_id). Inferred from discord_url or device_id when you send one of those alone.
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. |
stringNew https:// delivery URL. Alone, it moves a webhook between HTTPS (target_url) and in-app delivery (null or empty); a Discord or mobile-push webhook sends channel: "webhook" with it.
stringOnly with channel=discord. Discord incoming-webhook URL. Never returned after this call: reads show channel_config_present: true.
stringOnly with channel=mobile_push. Device to notify, from POST /v2/devices/register.
stringenumEvaluation cadence. Event and news webhooks deliver as they land, so only realtime is accepted on them.
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. |
stringNew display name. Non-empty, max 80 characters.
booleanfalse turns the webhook off. true turns a disabled webhook back on: your webhook limit is checked and the trigger is checked again. A plain re-enable starts clean and fires once for every current match; after a change to the trigger's filters (in this call or while it was off) it fires only on new matches.
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_configobjectMobile-push webhooks only: { device_id }, the device deliveries go to.
_metaobjectOnly when a new trigger 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 |
|---|---|
200 | The updated webhook record (signing_secret stripped). An empty body returns the current record unchanged. |
400 | Invalid id, an unknown field (strict: unknown keys are rejected, not ignored), a filter the webhook's trigger type does not take, or any value the subscribe that made the webhook refuses (invalid_query for a filter that cannot run). A Discord or mobile-push webhook sending target_url without channel, or a destination field for another channel (target_url with channel: "in_app"). On an event or news webhook, a new ticker list with any symbol we do not track (the message names them). universe_not_found: a new universe that does not exist; device_not_found: a new device_id that does not exist. |
403 | webhook_over_limit: enabled: true while the account holds more webhooks than the plan allows. |
404 | Webhook not found, or owned by another account. A universe, ticker or device_id in the body that does not exist is a 400 naming it, never a 404. |
Notes
- A webhook takes the filters of the subscribe that made it (
subscription_origin.type): a scan webhookq,universe,select,order,dir; a ticker webhookq,select; a signal webhookcondition,universe,select,order,dir; an event webhookkind,ticker,universe,q,select; a news webhooksearch,ticker,universe,min_relevance,q,select. Each is checked exactly as that subscribe checks it, and a filter you leave out keeps its value. - A changed trigger fires only on what is new. A scan, ticker or signal webhook records what already matches the new trigger at its next evaluation, without firing, then fires when a ticker starts matching; an event or news webhook fires only on what lands after the edit.
- A new destination (
target_url,channel,discord_url,device_id) starts a new delivery-failure streak.
More examples
Turn a disabled webhook back on
curl -X PATCH "https://api.tickerbot.io/v2/webhooks/wh_smRsF3-z36o" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'Show responseHide response
{
"as_of": "2026-11-11T14:05:00.000Z",
"id": "wh_smRsF3-z36o",
"name": "NVDA: gap_up AND high_volume_alert",
"q": "ticker = 'NVDA' AND (gap_up AND high_volume_alert)",
"status": "active",
"consecutive_failures": 0,
"failing_since": null,
"last_match_set": [],
"last_evaluated_at": null,
"...": "(the rest of the webhook record)"
}