# POST /v2/news/subscribe

**Subscribe to news**

Gets 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

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `search` | body | string | no | Full-text search over `title` + `summary`, as on [Query news](/docs/endpoints/news/query). Example: `stock split`. |
| `ticker` | body | string[] | no | One ticker or a comma list (up to 50): articles that mention any of them. Not combinable with `universe`. Example: `NVDA,AMD`. |
| `universe` | body | string | no | 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. Articles that mention any member fire. Example: `top_100`. |
| `min_relevance` | body | number | no | Only with `ticker` or `universe`. Only articles about one of the tickers (its `relevance` at least this value, 0 to 1). Example: `0.8`. |
| `q` | body | string | no | The filter, as on [Query news](/docs/endpoints/news/query): article fields and the per-mention fields `ticker`, `relevance`, `sentiment_score` and `sentiment`. An article fires once when any of its mentions matches. Example: `ticker = 'NVDA' AND sentiment_score < -0.3`. |
| `select` | body | string[] | no | The article fields each delivered article carries, besides `id` and `mentions` (always sent). Names only. Omitted: the Query news default row. Example: `title,url,summary`. |
| `channel` | body | string enum | no | 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](/docs/endpoints/webhooks#delivery-channels). One of the `channel` values below. |
| `target_url` | body | string | no | Only with `channel=webhook`. HTTPS URL each delivery is POSTed to. Example: `https://example.com/hook`. |
| `discord_url` | body | string | no | 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. |
| `device_id` | body | string | no | Only with `channel=mobile_push`. Device to notify, from [`POST /v2/devices/register`](/docs/endpoints/devices/register). An unknown id is a 400 `device_not_found`. |
| `name` | body | string | no | Display name, up to 80 characters. Defaults to `news: <scope> · <search or q>`. Example: `NVDA bears`. |

`channel` values:

| Value | Meaning |
|-------|---------|
| `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](/docs/endpoints/devices/register). |

## Headers

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `Idempotency-Key` | header | string | no | 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. |

## Returns

- `as_of` (string) — Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for ([As-of](/docs/asof)).
- `id` (string) — The webhook id (`wh_…`), the handle for every other call on this record.
- `name` (string) — Your label for the subscription.
- `q` (string) — 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`.
- `select` (string[]) — 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.
- `order` (string) — 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.
- `dir` (string enum) — Sort direction for those lists: `desc` unless you chose one. `null` on event and news webhooks.

  | Value | Meaning |
  |-------|---------|
  | `asc` | Ascending: smallest or earliest first. |
  | `desc` | Descending: largest or most recent first. |

- `universe` (string) — Universe the trigger is scoped to, or `null` for the whole market.
- `cadence` (string enum) — Scan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land.

  | Value | Meaning |
  |-------|---------|
  | `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. |

- `channel` (string enum) — Where deliveries go.

  | Value | Meaning |
  |-------|---------|
  | `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](/docs/endpoints/devices/register). |

- `target_url` (string) — Your HTTPS endpoint; `null` on every channel except `webhook`.
- `status` (string enum) — Whether it is live. `disabled_reason` says why a webhook is disabled.

  | Value | Meaning |
  |-------|---------|
  | `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_origin` (object) — Which subscribe route created it: `type` (`ticker`/`signal`/`scan`/`event`/`news`), its `ref` and the `condition` in display form.
- `created_at` (number) — Creation timestamp (epoch seconds).
- `updated_at` (number) — Last modification timestamp (epoch seconds).
- `last_fired` (number) — When a delivery last went out (epoch seconds); `null` if it never has.
- `last_match_set` (array) — 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_at` (number) — When the last evaluation error happened (epoch seconds); `null` on a healthy hook.
- `last_error` (string) — The last evaluation error; `null` on a healthy hook. The answer to "why is my webhook not firing?".
- `next_eval_at` (number) — When the evaluator will next consider this subscription (epoch seconds).
- `last_evaluated_at` (number) — Scan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); `null` until the first run.
- `kind` (string[] enum) — Event webhooks only: the kinds subscribed.

  | Value | Meaning |
  |-------|---------|
  | `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). |

- `ticker` (array) — Event and news webhooks only: the symbols it is scoped to, or `null` for the universe or the whole market.
- `search` (string) — News webhooks only: the full-text search it fires on, or `null`.
- `min_relevance` (number) — News webhooks only: the least `relevance` a scoped ticker needs, or `null`.
- `consecutive_failures` (number) — 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_at` (number) — When a delivery last reached your endpoint, in epoch seconds (`created_at` until the first one does).
- `failing_since` (number) — When the current failure streak began (epoch seconds); `null` while deliveries are succeeding.
- `channel_config_present` (boolean) — Discord and mobile-push webhooks: `true` when delivery settings are stored. The Discord URL itself is never returned after create.
- `disabled_reason` (string enum) — Disabled webhooks only: why it was turned off. Turn it back on with `PATCH /v2/webhooks/{webhook}` and `enabled: true`.

  | Value | Meaning |
  |-------|---------|
  | `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_code` (number) — After a `delivery_failure`: the HTTP status your endpoint last returned.
- `disabled_last_error` (string) — 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_explanation` (string) — After an `evaluation_failure`: what changed and what to use instead, for example the new name of a renamed signal.
- `disabled_at` (number) — After an `evaluation_failure`, `plan_downgrade` or `subscription_canceled`: when it was disabled (epoch seconds).
- `disable_email_sent_at` (number) — When we emailed you about the disable (epoch seconds).
- `channel_config` (object) — Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).
- `signing_secret` (string) — Returned on create only, and shown once. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries.
- `test_url` (string) — Returned on create only, when the channel delivers outside the dashboard: the path of `POST /v2/webhooks/{webhook}/test` for this record.
- `_meta` (object) — 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.

## Status codes

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

## Sample response

```json
{
  "as_of": "2026-11-11T16:40:00.000Z",
  "id": "wh_n4Qx8b-t21k",
  "name": "NVDA bears",
  "q": "ticker = 'NVDA' AND sentiment_score < -0.3",
  "search": null,
  "ticker": ["NVDA"],
  "min_relevance": null,
  "select": ["title", "url", "source"],
  "universe": null,
  "channel": "webhook",
  "target_url": "https://example.com/hook",
  "status": "active",
  "subscription_origin": { "type": "news", "ref": "NVDA", "condition": "ticker = 'NVDA' AND sentiment_score < -0.3" },
  "signing_secret": "whsec_…",
  "created_at": 1794415200,
  "…": "(the rest of the webhook object)",
  "test_url": "/v2/webhooks/wh_n4Qx8b-t21k/test"
}
```

## Notes

- Creates a webhook; list, update and delete it at [`/v2/webhooks`](/docs/endpoints/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_url` to 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"` with `articles`, each the article row as [Query news](/docs/endpoints/news/query) returns it (or the `select` fields) plus `id` and `mentions`, oldest first, up to 100 per delivery; `article_count` is how many this delivery carries. The payload also echoes `search`, `ticker`, `universe` and `q`. Receivers handling several webhook types should branch on the `event` field.

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/news/subscribe
