Webhooks
Manages your subscriptions: each pairs a screen, a signal, a ticker, an event feed or a news feed with a delivery we push when it fires. Create them with the subscribe call on Scan, Signals, Tickers, Events or News.
Endpoints
| Method | Path | MCP tool | Summary |
|---|---|---|---|
| GET | /v2/webhooks | tickerbot_list_webhooks | Lists every webhook on your account. |
| GET | /v2/webhooks/{webhook} | tickerbot_get_webhook | Returns one webhook. |
| PATCH | /v2/webhooks/{webhook} | tickerbot_update_webhook | Edits a webhook in place: its trigger, delivery, name or state. |
| DELETE | /v2/webhooks/{webhook} | tickerbot_delete_webhook | Deletes a webhook. |
| POST | /v2/webhooks/{webhook}/test | tickerbot_test_webhook | Sends a sample delivery to your endpoint, instantly. |
| GET | /v2/webhooks/{webhook}/deliveries | tickerbot_list_webhook_deliveries | Lists a webhook's recent deliveries. |
| POST | /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver | tickerbot_redeliver_webhook_delivery | Resends a past delivery to your endpoint. |
Five ways to create one
Subscribe from what you are watching: POST /v2/scan/subscribe takes the q of a screen (a signal on its own is a screen: q=golden_cross), POST /v2/signals/{signal}/subscribe one signal, POST /v2/tickers/{ticker}/subscribe a condition on one ticker, POST /v2/events/subscribe an event feed and POST /v2/news/subscribe a news feed. Each returns the same webhook object, which you manage here.
State-change deduplication
We track each ticker’s match state per webhook and deliver only when a ticker goes from not matching to matching. A ticker that flickers true → false → true inside a minute fires once; one that stays matched for three days fires once, when it first matched. To fire again it has to leave the match set first. Event and news triggers have no match state: each new event or article fires once.
Cadence sets the granularity. The match state is captured when the webhook is evaluated, and cadence controls how often that is: on realtime the flicker window is the ~1-minute refresh, but on hourly or nyse_open the window is the whole gap between evaluations. A ticker that enters and exits entirely between two evaluations never fires at all, and repeated flicker inside the window collapses to at most one event.
Polling is different: Run a scan (POST /v2/scan), List tickers and Get a signal always return current state with no deduplication. To get edge-triggered behavior from a poll, diff the result set yourself between calls.
Delivery channels
One discriminator, set when you subscribe. Each subscription delivers to one of: an HTTPS endpoint, a Discord channel, the Tickerbot mobile app or only the dashboard.
webhook: POST a signed JSON payload (webhook.fired,events.firedornews.fired) to yourtarget_url.discord: post a formatted embed to a Discord channel via an incoming-webhook URL. No HMAC: the URL is the credential.in_app: record fires in the dashboard’s deliveries timeline only. No outbound request.mobile_push: push a notification to a phone signed in to the Tickerbot app; the app registers itself.
If you omit channel, it’s inferred: discord when discord_url is set, else mobile_push when device_id is set, else webhook when target_url is set, otherwise in_app. To switch channels later, send channel to Update a webhook.
Discord
Post embeds to a channel with two extra fields.
In Discord, open Server Settings → Integrations → Webhooks → New Webhook, pick a channel, and Copy Webhook URL. Pass it as discord_url with channel: "discord" on any subscribe endpoint:
curl -X POST "https://api.tickerbot.io/v2/scan/subscribe" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "above_sma_200 AND market_cap > 1e10",
"channel": "discord",
"discord_url": "https://discord.com/api/webhooks/123456789012345678/aBcDeF…",
"cadence": "realtime"
}'Each fire posts a single embed with the subscription name. A screen lists up to the first dozen matching tickers with price and day change, plus an “…and N more” line; an event webhook lists up to 12 events and a news webhook up to 10 linked headlines. Discord embed limits apply: long lists are truncated, not split.
The URL is a credential, so we store it as one: the create response echoes it once, and every read after omits it (channel_config_present: true). To rotate it, send a new discord_url to Update a webhook.
Delivery payloads
The JSON body POSTed to a target_url. X-Tickerbot-Event names which one it is.
webhook.fired
Scan, signal and ticker webhooks. One or more tickers started matching since the last evaluation. One delivery per evaluation that has a new match; a ticker that stays matched does not fire again.
| Field | Type | Meaning | ||||
|---|---|---|---|---|---|---|
event | string | webhook.fired. | ||||
webhook_id | string | The webhook that fired. | ||||
name | string | The webhook’s name. | ||||
q | string | The webhook’s rule. | ||||
universe | string or null | The webhook’s universe, or null when it is not scoped to one. | ||||
as_of | timestamp | When the evaluation ran (ISO 8601). | ||||
matches | object[] | The tickers that started matching, up to 100, in the webhook’s order and dir (default market_cap, descending). Each is a scan row: the default row (ticker, name, asset_class, asset_type, price, change_1d_pct, gap_pct, relative_volume, market_cap) plus the signals in q and order. A webhook with select gets ticker plus exactly those signals. | ||||
current_matches | object[] | Every ticker matching now, new and old, up to 100, in the same order and row shape. | ||||
matched_count | integer | How many tickers started matching, counted in full when matches is cut. | ||||
current_match_count | integer | How many tickers match now, counted in full when current_matches is cut. | ||||
matches_truncated | boolean | Present and true when matches was cut at 100. | ||||
current_matches_truncated | boolean | Present and true when current_matches was cut at 100. | ||||
order | string | Present when a list was cut: the signal the 100 were taken by. | ||||
dir | string enum | Present when a list was cut: the direction the 100 were taken in.
|
{
"event": "webhook.fired",
"webhook_id": "wh_8f3a2bQx1LmP",
"name": "gappers on volume",
"q": "gap_up AND relative_volume > 2",
"universe": null,
"as_of": "2026-11-12T17:02:35.862Z",
"matches": [
{
"ticker": "AVEX",
"name": "AEVEX Corp.",
"asset_class": "stocks",
"asset_type": "CS",
"price": 14.27,
"change_1d_pct": 17.6422,
"gap_pct": 12.5309,
"relative_volume": 2.1597,
"market_cap": 987449838,
"gap_up": true
}
],
"current_matches": [
{
"ticker": "TRMK",
"name": "Trustmark Corp",
"asset_class": "stocks",
"asset_type": "CS",
"price": 48.012,
"change_1d_pct": 5.3819,
"gap_pct": 5.4434,
"relative_volume": 4.1729,
"market_cap": 2771974837,
"gap_up": true
},
{
"ticker": "AVEX",
"name": "AEVEX Corp.",
"asset_class": "stocks",
"asset_type": "CS",
"price": 14.27,
"change_1d_pct": 17.6422,
"gap_pct": 12.5309,
"relative_volume": 2.1597,
"market_cap": 987449838,
"gap_up": true
}
],
"matched_count": 1,
"current_match_count": 2
}events.fired
Event webhooks (Subscribe to events). New events of the watched kinds landed for the watched tickers. Each event fires once; only events from the last 7 days fire.
| Field | Type | Meaning | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
event | string | events.fired. | ||||||||||||||
webhook_id | string | The webhook that fired. | ||||||||||||||
name | string | The webhook’s name. | ||||||||||||||
kind | string[] enum | The event kinds the webhook watches.
| ||||||||||||||
q | string or null | The webhook’s filter, or null when it has none. | ||||||||||||||
ticker | string[] or null | The webhook’s tickers, or null. | ||||||||||||||
universe | string or null | The webhook’s universe, or null. | ||||||||||||||
as_of | timestamp | When the delivery was built (ISO 8601). | ||||||||||||||
events | object[] | The new events, up to 2,000, each a Query events row: id, ticker, ts, kind and payload. A webhook with select gets id, ticker, ts and kind plus the named fields. | ||||||||||||||
event_count | integer | How many new events, counted in full when events is cut. | ||||||||||||||
events_truncated | boolean | Present and true when events was cut at 2,000. |
{
"event": "events.fired",
"webhook_id": "wh_kJv8Bn4Yx2Pq",
"name": "AAPL dividends",
"kind": ["dividend"],
"q": null,
"ticker": ["AAPL"],
"universe": null,
"as_of": "2026-11-12T17:02:09.118Z",
"events": [
{
"id": "dividend:AAPL|2026-11-12|CD|0.27",
"ticker": "AAPL",
"ts": "2026-11-12T00:00:00.000Z",
"kind": "dividend",
"payload": {
"amount": 0.27,
"ex_date": "2026-11-12",
"pay_date": "2026-11-16",
"record_date": "2026-11-12",
"declared_date": "2026-11-02",
"dividend_type": "CD",
"frequency": 4
}
}
],
"event_count": 1
}news.fired
News webhooks (Subscribe to news). New articles matching the webhook’s filter landed. Each article fires once; only articles from the last 2 days fire. More than 100 new articles go out as several deliveries.
| Field | Type | Meaning |
|---|---|---|
event | string | news.fired. |
webhook_id | string | The webhook that fired. |
name | string | The webhook’s name. |
search | string or null | The webhook’s search, or null. |
ticker | string[] or null | The webhook’s tickers, or null. |
universe | string or null | The webhook’s universe, or null. |
min_relevance | number or null | The webhook’s min_relevance, or null. |
q | string or null | The webhook’s filter, or null. |
as_of | timestamp | When the delivery was built (ISO 8601). |
articles | object[] | Up to 100 new articles, each a Query news row with its mentions. A webhook with select gets id, the named fields and mentions. |
article_count | integer | How many articles this delivery carries. |
{
"event": "news.fired",
"webhook_id": "wh_Tq7mR2vNc8Lz",
"name": "NVDA news",
"search": null,
"ticker": ["NVDA"],
"universe": null,
"min_relevance": null,
"q": null,
"as_of": "2026-11-12T17:02:20.845Z",
"articles": [
{
"id": 4990877,
"time_published": "2026-11-12T16:15:37.000Z",
"title": "Qualcomm Inc Stock (QCOM) Moved Up by 3.20% on Nov 12: Facts Behind the Movement",
"url": "https://www.tradingkey.com/news/market-movers/262302990-market-movers-qcom-20261112",
"source": "TradingKey",
"tickers": ["QCOM", "NVDA", "AMD", "AVGO", "AAPL"],
"overall_sentiment_score": 0.0754,
"overall_sentiment_label": "Neutral",
"mentions": [
{ "ticker": "QCOM", "relevance": 1, "sentiment_score": 0.352447, "sentiment": "Bullish" },
{ "ticker": "NVDA", "relevance": 0.634332, "sentiment_score": -0.38981, "sentiment": "Bearish" },
{ "ticker": "AMD", "relevance": 0.643394, "sentiment_score": 0.398435, "sentiment": "Bullish" },
{ "ticker": "AVGO", "relevance": 0.603063, "sentiment_score": 0.369219, "sentiment": "Bullish" },
{ "ticker": "AAPL", "relevance": 0.620415, "sentiment_score": -0.381356, "sentiment": "Bearish" }
]
}
],
"article_count": 1
}Verifying deliveries
Every delivery to a target_url carries an X-Tickerbot-Signature header. Check it before you trust the body: a valid signature proves the request came from Tickerbot and the body arrived unchanged.
| Header | Meaning |
|---|---|
Content-Type | Always application/json. |
User-Agent | Always Tickerbot-Webhooks/1.0. |
X-Tickerbot-Event | The event name: webhook.fired for scan, signal and ticker webhooks, events.fired for event webhooks, news.fired for news webhooks. Route on it in your handler. |
X-Tickerbot-Delivery-Id | Identifies the delivery. It stays the same across retries and resends (POST /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver sends the original id), so use it to drop duplicates. |
X-Tickerbot-Webhook-Id | The webhook that produced the delivery. |
X-Tickerbot-Signature | HMAC-SHA256 signature, t=<unix-timestamp>,v1=<hex-digest>. The signed payload is <timestamp>.<raw-body>, keyed with the webhook’s signing_secret. |
X-Tickerbot-Test | true on deliveries sent by POST /v2/webhooks/{webhook}/test, and absent on real fires. A test is the same shape as a real fire, with the same headers and signature, and carries one sample match, event or article (ticker TBOT; each signal a sample value of its type: text, an ISO timestamp, a number or true), so a receiver can filter tests on this header. |
The key is the webhook’s signing_secret (whsec_…), returned in the response of the subscribe call that created the webhook. Store it then: the create response is the one place it appears. Each webhook has its own.
- Split the header on commas and read
t(the Unix time the delivery was signed) andv1(the hex signature). - Compute HMAC-SHA256 over
<t>.<raw-body>with thesigning_secretas the key, and hex-encode it. Use the body bytes exactly as received: parsing and re-serializing the JSON changes them. - Compare your digest with
v1in constant time (crypto.timingSafeEqualin Node,hmac.compare_digestin Python). Reject the delivery on a mismatch. - Reject a delivery whose
tis more than 5 minutes from your clock, so a captured request cannot be replayed. Each attempt is signed when it is sent, retries and resends included.
const crypto = require('crypto')
const express = require('express')
const app = express()
// express.raw keeps the body as the exact bytes we signed.
app.post('/webhooks/tickerbot', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('X-Tickerbot-Signature') || ''
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')))
const t = parts.t
const sig = parts.v1 || ''
if (!t || !sig) return res.status(400).send('missing signature')
const expected = crypto
.createHmac('sha256', process.env.TICKERBOT_SIGNING_SECRET)
.update(`${t}.`)
.update(req.body)
.digest('hex')
const ok = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
if (!ok) return res.status(401).send('bad signature')
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(401).send('stale')
const delivery = JSON.parse(req.body)
// ... handle delivery.event
res.sendStatus(200)
})import hashlib, hmac, os, time
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ['TICKERBOT_SIGNING_SECRET'].encode()
@app.post('/webhooks/tickerbot')
def tickerbot_webhook():
header = request.headers.get('X-Tickerbot-Signature', '')
parts = dict(p.strip().split('=', 1) for p in header.split(',') if '=' in p)
t, sig = parts.get('t'), parts.get('v1', '')
if not t or not sig:
return 'missing signature', 400
body = request.get_data() # the raw bytes, before any JSON parsing
expected = hmac.new(SECRET, t.encode() + b'.' + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, expected):
return 'bad signature', 401
if abs(time.time() - int(t)) > 300:
return 'stale', 401
delivery = request.get_json()
# ... handle delivery['event']
return '', 200Retries & failures
A delivery that doesn’t get a 2xx is retried 7 times: 30s → 2m → 10m → 1h → 3h → 6h → 12h, about 22 hours in all. After that it is permanent_failure. Each attempt times out after 10 seconds.
Discord deliveries ride the same retry ladder, with one twist. A 2xx (Discord returns 204) is a success. A 429 is retried, honoring Discord’s Retry-After. Other 4xx responses (e.g. a deleted webhook → 404) are permanent_failure, with no retry. 5xx and network errors retry on the standard ladder.
The first time a delivery fails for good, we email you; one email per failure streak. failing_since on the webhook says when the streak began. If deliveries have kept failing for 72 hours (since failing_since) with none getting through, the next delivery that fails for good disables the webhook. Any delivered or failed delivery can be resent (not a test fire; the webhook must be on) with POST /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver.
When a webhook is disabled
The record says why, in disabled_reason.
user_disabled: you turned it off withPATCHandenabled: false.delivery_failure: deliveries kept failing for 72 hours with none getting through. We email you before this happens and again when it does. Fix the endpoint, re-enable, then resend what failed from the delivery log.evaluation_failure: the trigger can no longer run, for example it names a signal that has since been renamed. We disable it on the first failed evaluation and email you the replacement;disabled_explanationsays what changed. Correct the trigger withPATCH /v2/webhooks/{webhook}, then turn it back on.plan_downgrade: your webhook limit went down. Your oldest webhooks stay on up to the new limit and the newest are turned off; we email you how many. Delete webhooks to get within the limit, then turn them back on.subscription_canceled: your subscription ended. Resubscribe to turn them back on.
Turning a webhook back on (PATCH with enabled: true) re-checks the trigger first and returns 400 with the reason if it still can’t run.
Test it
Test fire works on every channel but the dashboard.
POST /v2/webhooks/{webhook}/test sends a sample fire to the webhook’s channel right now: the same shape, headers and signature as a real one, with one sample match, event or article (for Discord, a real embed with a [TEST] title prefix) and returns the inline outcome. It’s one-shot: failures don’t retry or count toward auto-disable.