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

  • Name
    Public API
    Type
    project API key
    Description

    Webhook metrics, backlog, and project usage are Public API routes.

  • Name
    Dashboard
    Type
    session auth
    Description

    The dashboard renders these same metrics as charts and adds time-bucketed delivery summaries for the project overview.

  • Name
    SDK / CLI
    Description

    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

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

Read backlog pressure

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

Read project usage with the SDK

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 renders time-bucketed delivery summaries as trend charts, mostly to give operators recent context alongside auto-refreshed delivery views. 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
  • 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.

Was this page helpful?