Monitoring & events

**OwlViz** change monitoring watches assets and collections for semantic metadata, health, authority, and image changes. Webhooks deliver monitor and market change events asynchronously (HMAC-signed POST, worker retries).

Base URL: https://api.owlviz.dev

Public reads vs writes

**Self-serve change monitor writes** use your portal API key:

Authorization: Bearer ov_live_…

Plan quotas (activeChangeMonitors): Free **1**, Builder **5**, Pro **20** (active, non-disabled monitors). Minimum intervalSeconds for keyed creates/updates is **3600**. Manual POST /v1/monitors/:id/check remains **admin-only** (MONITORING_ADMIN_TOKEN).

**Operator / legacy monitors** (owner_account_id null) are created with the admin token and may use tighter poll intervals configured server-side. Monitor-event webhook fanout for ownerless monitors delivers only to **ownerless** (ops) webhook endpoints. Account-owned monitors fan out only to webhook endpoints with the same owner_account_id. Market-event webhook fanout is unchanged (all matching subscriptions).

**Webhook and Market Watch writes** use your portal API key (ov_live_…) within plan quotas, or the same admin token for operator workflows. Manage subscriptions from the dashboard at /developer/webhooks, /developer/change-monitors, and /developer/market-watches without pasting keys into the browser.

Production default: PUBLIC_MONITORING_WRITES=false — **admin-path** monitor writes return **403** MONITORING_WRITES_FORBIDDEN when disabled (API key writes still work). Set MONITORING_ADMIN_TOKEN server-side only — never in NEXT_PUBLIC_* or client bundles.

The public scanner is **read-only** for change monitors — no create/check UI. Monitor, webhook, and Market Watch CRUD live in the developer portal. On asset/collection scanner pages, the Monitoring panel loads **your** change monitors via signed-in portal session (BFF); signed-out visitors see a sign-in CTA instead of anonymous monitor lists.

Monitor endpoints

Create monitor (self-serve)

curl -sS -X POST "$API_BASE/v1/monitors" \
  -H "Authorization: Bearer ov_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "asset",
    "target": "C5gHBKXwA8jduXNk3HyAVLnLBN6PEM8fTqkNNh5uyyjJ",
    "intervalSeconds": 3600,
    "events": ["metadata.changed", "health.degraded"]
  }'

Operator-only create (ownerless legacy monitor, tighter intervals allowed):

curl -sS -X POST "$API_BASE/v1/monitors" \
  -H "Authorization: Bearer $MONITORING_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "asset",
    "target": "C5gHBKXwA8jduXNk3HyAVLnLBN6PEM8fTqkNNh5uyyjJ",
    "intervalSeconds": 3600,
    "events": ["metadata.changed", "health.degraded"]
  }'

Monitor fields: targetType (asset | collection), target (mint/address), intervalSeconds, events (non-empty array from allowed enum).

Serialized monitor includes waitingForIndex (true when a collection monitor awaits indexing), lastCheckedAt, nextCheckAt, consecutiveFailures, etc.

Event types (actual enum members)

Asset events

Collection events

Webhook test

Event listing

GET /v1/events — global feed with filters:

Event payload:

{
  "data": [
    {
      "id": "...",
      "monitorId": "...",
      "targetType": "asset",
      "target": "...",
      "type": "health.degraded",
      "severity": "warning",
      "summary": "...",
      "before": {},
      "after": {},
      "diff": { "changes": [] },
      "snapshotIdBefore": "...",
      "snapshotIdAfter": "...",
      "occurredAt": "...",
      "createdAt": "..."
    }
  ],
  "pagination": { "nextCursor": null }
}

Semantic diff behavior

• **Baseline on first success** — the first successful check stores a baseline; later checks diff against it.
• **Excluded operational fields** — cache timestamps, transient resolver diagnostics, and similar fields are excluded from semantic diffs.
• **Attribute/creator normalization** — attributes and creators are normalized before comparison to reduce false positives.
• **Health band hysteresis** — health events fire on band changes (healthy / warning / degraded / critical), not every point change.
• **Image/metadata hysteresis** — image and metadata failure/recovery events use hysteresis to avoid flapping.
• **Event fingerprints** — each persisted event gets a deterministic SHA-256 fingerprint from monitorId, event type, and semantic before/after state hashes. The database enforces a unique index on fingerprint with ON CONFLICT DO NOTHING, so repeated checks that detect the same semantic state do not insert duplicate events or re-trigger webhook delivery storms. Content hashes also participate in image change detection when available.

Image monitoring limitation

Asset image checks read **stored media-recovery state** from the database rather than actively revalidating media on every monitor cycle. Events may lag until media recovery runs elsewhere.

Webhooks

See [webhooks.md](../webhooks.md) for delivery headers, HMAC verification, retries, and payload shape.

Webhook write routes accept a portal API key (Builder+ quota) or ops admin token. POST /v1/webhooks returns the signing secret **once** at creation — store it securely.

Subscription event types

Monitor events (asset/collection), market change events (spot_floor_changed, reference_floor_changed, provider_floor_changed, provider_status_changed), wildcard *, and synthetic webhook.test.

Delivery records (Sprint 6.2)

Each delivery includes monitorEventId or marketEventId, status, attempt, nextRetryAt, lastErrorCode, httpStatus, and responseTimeMs. Failed deliveries retry with exponential backoff until WEBHOOK_MAX_ATTEMPTS, then move to terminal dead. See [webhooks.md](../webhooks.md) for the full lifecycle.

Market change events (read API)

Durable market events are listed publicly — they are **not** mixed into GET /v1/events (monitor feed):

Event types: spot_floor_changed, reference_floor_changed, provider_floor_changed, provider_status_changed. See [Collections — Sprint 6](./collections.md#sprint-6--market-change-events-internal-durable-events) for detection semantics.

Subscribe to push delivery with POST /v1/webhooks and market event types in events. Example: [13-market-webhook.sh](./examples/13-market-webhook.sh).

Collection monitor freshness

COLLECTION_MONITOR_FRESHNESS_SECONDS (default **3600**): collection monitors treat indexes older than this threshold as stale and re-enqueue background indexing. Monitors may report waitingForIndex: true until coverage is sufficient.