# Delivery Analytics

Delivery analytics help operators explain throughput, backlog, failure pressure, and recent health trends without replacing the canonical delivery feed. Use this layer for dashboards, alert correlation, and short-horizon capacity questions.

## Analytics model

Hooksbase exposes three complementary analytics surfaces:

- webhook metrics for delivery outcomes over a time window
- webhook backlog history and current queue depth shape
- project usage and delivery summaries for billing and dashboard rollups

This is visibility data, not the enforcement plane. Quota admission still happens separately during ingest, replay, and file retention decisions.

## Auth model

- **Public API** `project API key`: Webhook metrics, backlog, and project usage are Public API routes.
- **Dashboard** `session auth`: The [dashboard](/docs/dashboard.md) renders these same metrics as charts and adds time-bucketed delivery summaries for the project overview.
- **SDK / CLI**: The SDK and CLI cover project usage. They do not wrap metrics or backlog routes yet, so use raw HTTP for those endpoints.

## Metrics, backlog, and usage

The primary routes are:

- `GET /v1/webhooks/{id}/metrics`
- `GET /v1/webhooks/{id}/backlog`
- `GET /v1/usage?from=&to=&webhookId=...`

Metrics and backlog use a `window` query value of `1h`, `24h`, `7d`, or `30d`; when omitted, the default is `24h`. Usage uses explicit `from` and `to` epoch-millisecond bounds.

Use them for different questions:

- metrics answer success, failure, and throughput questions for one webhook
- backlog answers queue-shape and pressure questions for one webhook
- usage answers project-wide delivery consumption questions across a time range

**Read webhook metrics**

```bash
curl -G https://api.hooksbase.com/v1/webhooks/wh_123/metrics \
  -H "Authorization: Bearer swk_..." \
  -d window=24h
```

**Read backlog pressure**

```bash
curl -G https://api.hooksbase.com/v1/webhooks/wh_123/backlog \
  -H "Authorization: Bearer swk_..." \
  -d window=24h
```

**Read project usage with the SDK**

```ts
const usage = await client.usage.get({
  from: 1740000000000,
  to: 1740086400000,
  webhookId: 'wh_123',
})
```

Analytics routes can return `503 Analytics unavailable.` when the underlying analytics layer is not available.

## Delivery summaries and caveats

The [dashboard](/docs/dashboard.md) renders time-bucketed delivery summaries as trend charts, mostly to give operators recent context alongside [auto-refreshed delivery views](/docs/dashboard-live-updates.md). Those summaries are a UI feature — they are not available as a public API surface. Use the Public API routes above when you need programmatic access.

Quota caveat:

- analytics visibility can lag or be unavailable
- quota enforcement still happens independently at ingest and replay time
- do not treat a healthy metrics view as proof that no quota boundary is near

## Related routes

- `GET /v1/webhooks/{id}/metrics`
- `GET /v1/webhooks/{id}/backlog`
- `GET /v1/usage`

## Common mistakes

- Treating analytics as the source of quota truth.
- Assuming metrics and backlog are covered by the first-party SDK or CLI.
- Using delivery summaries when you actually need canonical delivery detail.
- Ignoring `503 Analytics unavailable` and treating it like an empty dataset.