Developer events

Usagey records usage checks, tracked events, checkout creation, subscription changes, webhooks, payments, refunds, and failed entitlement decisions.

The dashboard's Developer events page combines paginated history with a live server-sent events feed. Server integrations can consume the same workspace history with a secret API key.

Filter the live feed by API calls, webhooks, entitlements, or billing events without leaving the active workspace.

API-key history

GET /v1/events returns newest-first history for the workspace and environment represented by the API key and selected host.

import { Usagey } from "@usagey/sdk";

const usagey = new Usagey(process.env.USAGEY_API_KEY!);
const page = await usagey.events.list({
  eventType: 'WEBHOOK_PROCESSED',
  status: 'ERROR',
  take: 50,
});

if (page.hasMore && page.nextCursor) {
  const nextPage = await usagey.events.list({cursor: page.nextCursor});
}

The REST equivalent is:

curl --get 'https://api.usagey.com/v1/events' \
  --header "Authorization: Bearer $USAGEY_API_KEY" \
  --data-urlencode 'eventType=WEBHOOK_PROCESSED' \
  --data-urlencode 'status=ERROR' \
  --data-urlencode 'take=50'

History and replay

GET /api/developer-events returns newest-first event history for the authenticated operator's selected organization and environment. Use take from 1 to 200, then pass nextCursor into the next request while hasMore is true.

Optional filters are eventType, status, and search. Search matches event messages and sources. Cursors are validated against the selected workspace, so a cursor copied from another organization or environment returns 400.

curl --get 'https://usagey.com/api/developer-events' \
  --data-urlencode 'organizationId=org_123' \
  --data-urlencode 'env=production' \
  --data-urlencode 'eventType=WEBHOOK_PROCESSED' \
  --data-urlencode 'status=ERROR' \
  --data-urlencode 'take=50'

Live stream

GET /api/developer-events/stream is an authenticated dashboard endpoint. It uses the active organization and environment query parameters and the operator's Usagey session.

const events = new EventSource(
  "/api/developer-events/stream?organizationId=org_123&env=sandbox",
);

events.onmessage = ({ data }) => {
  console.log(JSON.parse(data));
};

History, webhook diagnostics, and the stream establish an operator-scoped workspace boundary before reading event data. The stream closes that authorization transaction before opening its long-lived connection.

The session-authenticated endpoints remain intended for the Usagey console. API-key integrations should use /v1/events. A public live stream is intentionally deferred until event fan-out uses shared infrastructure rather than process-local delivery.