Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

usageEventIdstring

The usage event ID.

subscriptionIdstring

The subscription ID.

customerIdstring

The customer ID. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.

featureCodestring

The feature code the usage was tracked against.

valuenumber

The recorded quantity. For AI model events this is the total token count.

tsstring

ISO 8601 timestamp of the usage event.

{
  "event": "usage.recorded",
  "timestamp": "2026-06-18T09:12:03.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "usageEventId": "evt_9f8e7d6c",
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "featureCode": "api_calls",
    "value": 25,
    "ts": "2026-06-18T09:12:00.000Z"
  }
}

When this fires

Once per processed usage event, after the async processor persists it. This is the only high-volume webhook: it fires at your own ingest rate, so it is excluded from the family select-all in the dashboard and must be subscribed to explicitly.

Delivery is asynchronous — events are batched through the usage pipeline, so expect seconds of delay relative to the original POST /usage/events call. The idempotency key is the usage event ID, so retries never duplicate.

Use it to mirror usage into your own analytics store without polling.