tickerbot.io
Endpoints › Webhooks

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

MethodPathMCP toolSummary
GET/v2/webhookstickerbot_list_webhooksLists every webhook on your account.
GET/v2/webhooks/{webhook}tickerbot_get_webhookReturns one webhook.
PATCH/v2/webhooks/{webhook}tickerbot_update_webhookEdits a webhook in place: its trigger, delivery, name or state.
DELETE/v2/webhooks/{webhook}tickerbot_delete_webhookDeletes a webhook.
POST/v2/webhooks/{webhook}/testtickerbot_test_webhookSends a sample delivery to your endpoint, instantly.
GET/v2/webhooks/{webhook}/deliveriestickerbot_list_webhook_deliveriesLists a webhook's recent deliveries.
POST/v2/webhooks/{webhook}/deliveries/{delivery}/redelivertickerbot_redeliver_webhook_deliveryResends 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.fired or news.fired) to your target_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.

FieldTypeMeaning
eventstringwebhook.fired.
webhook_idstringThe webhook that fired.
namestringThe webhook’s name.
qstringThe webhook’s rule.
universestring or nullThe webhook’s universe, or null when it is not scoped to one.
as_oftimestampWhen the evaluation ran (ISO 8601).
matchesobject[]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_matchesobject[]Every ticker matching now, new and old, up to 100, in the same order and row shape.
matched_countintegerHow many tickers started matching, counted in full when matches is cut.
current_match_countintegerHow many tickers match now, counted in full when current_matches is cut.
matches_truncatedbooleanPresent and true when matches was cut at 100.
current_matches_truncatedbooleanPresent and true when current_matches was cut at 100.
orderstringPresent when a list was cut: the signal the 100 were taken by.
dirstring enumPresent when a list was cut: the direction the 100 were taken in.
ascAscending: smallest or earliest first.
descDescending: largest or most recent first.
webhook.fired sample
{
  "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.

FieldTypeMeaning
eventstringevents.fired.
webhook_idstringThe webhook that fired.
namestringThe webhook’s name.
kindstring[] enumThe event kinds the webhook watches.
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).
qstring or nullThe webhook’s filter, or null when it has none.
tickerstring[] or nullThe webhook’s tickers, or null.
universestring or nullThe webhook’s universe, or null.
as_oftimestampWhen the delivery was built (ISO 8601).
eventsobject[]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_countintegerHow many new events, counted in full when events is cut.
events_truncatedbooleanPresent and true when events was cut at 2,000.
events.fired sample
{
  "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.

FieldTypeMeaning
eventstringnews.fired.
webhook_idstringThe webhook that fired.
namestringThe webhook’s name.
searchstring or nullThe webhook’s search, or null.
tickerstring[] or nullThe webhook’s tickers, or null.
universestring or nullThe webhook’s universe, or null.
min_relevancenumber or nullThe webhook’s min_relevance, or null.
qstring or nullThe webhook’s filter, or null.
as_oftimestampWhen the delivery was built (ISO 8601).
articlesobject[]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_countintegerHow many articles this delivery carries.
news.fired sample
{
  "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.

HeaderMeaning
Content-TypeAlways application/json.
User-AgentAlways Tickerbot-Webhooks/1.0.
X-Tickerbot-EventThe 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-IdIdentifies 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-IdThe webhook that produced the delivery.
X-Tickerbot-SignatureHMAC-SHA256 signature, t=<unix-timestamp>,v1=<hex-digest>. The signed payload is <timestamp>.<raw-body>, keyed with the webhook’s signing_secret.
X-Tickerbot-Testtrue 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.

  1. Split the header on commas and read t (the Unix time the delivery was signed) and v1 (the hex signature).
  2. Compute HMAC-SHA256 over <t>.<raw-body> with the signing_secret as the key, and hex-encode it. Use the body bytes exactly as received: parsing and re-serializing the JSON changes them.
  3. Compare your digest with v1 in constant time (crypto.timingSafeEqual in Node, hmac.compare_digest in Python). Reject the delivery on a mismatch.
  4. Reject a delivery whose t is 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.
Node.js (Express)
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)
})
Python (Flask)
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 '', 200

Retries & 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 with PATCH and enabled: 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_explanation says what changed. Correct the trigger with PATCH /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.