> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchlist + alerts

> Watch any ticker, query, URL, or text — get webhooks, emails, or Telegram pings when conditions trip.

The watchlist + alerts system has three layers:

1. **Watched objects** — what you're tracking (ticker, query, URL, text).
2. **Alert rules** — conditions on watched objects (`price_above`, `price_below`, `econ_release`, `gov_action`, `semantic_match`).
3. **Webhook endpoints** — where alerts get delivered.

## Add to watchlist

```bash theme={null}
sf watchlist add KXRATECUT-26DEC31
sf watchlist identify "Will the Fed cut rates by July?" --json
sf watchlist list --json
```

`identify` resolves a free-text query, URL, or ticker into a canonical watched object. The CLI handles dedupe and lifecycle.

## Create an alert rule

```bash theme={null}
sf alerts create \
  --object <watched-object-id> \
  --condition price_above \
  --threshold 65 \
  --channel webhook \
  --endpoint <webhook-endpoint-id>
```

Conditions:

| Condition        | Trigger                                  |
| ---------------- | ---------------------------------------- |
| `price_above`    | Yes price ≥ threshold (cents)            |
| `price_below`    | Yes price ≤ threshold (cents)            |
| `econ_release`   | FRED series prints (e.g., CPI release)   |
| `gov_action`     | Bill / nomination / treaty status change |
| `semantic_match` | LLM-classified content match             |

Each rule is `active`, `paused`, or `archived`. Test with `sf alerts test <id>`.

## Register a webhook endpoint

```bash theme={null}
sf webhooks create \
  --url https://your.app/sf-alerts \
  --label "ops-alerts"
```

Returns the endpoint id and a signing secret. Subsequent deliveries include:

```http theme={null}
X-SF-Signature: t=1714572345,v1=hex(hmac_sha256(secret, "{t}.{body}"))
X-SF-Endpoint-Id: we_...
X-SF-Delivery-Id: del_...
```

See [Webhook receiver](/integrations/webhook-receiver) for verification code samples.

## Delivery and dedupe

Alert delivery is idempotent per rule, channel, endpoint, and window. A rule should not re-fire the same condition more than once inside its dedupe window. Webhook receivers should also idempotency-key on `X-SF-Delivery-Id`.

## Runtime architecture

The evaluator runs server-side. It uses live market data where available and falls back to REST snapshots when needed. Users configure watched objects, alert rules, channels, endpoints, and dedupe windows; they do not need to run a local process for server-side alerts.

## Next steps

<CardGroup cols={2}>
  <Card title="Watch + alert API" href="/api-reference/watch-alerts">
    Endpoint shapes and curl examples.
  </Card>

  <Card title="Webhook events" href="/reference/webhook-events">
    Every event payload shape.
  </Card>

  <Card title="Webhook receiver" href="/integrations/webhook-receiver">
    Verification + retry handling code samples.
  </Card>

  <Card title="Webhooks" href="/build/webhooks">
    Endpoint registration and signing.
  </Card>
</CardGroup>