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"
  }
}

Cuándo se dispara

Una vez por cada evento de uso procesado, después de que el procesador asíncrono lo persiste. Este es el único webhook de alto volumen: se dispara a tu propia tasa de ingesta, por lo que se excluye del "seleccionar todo" de la familia en el dashboard y debe suscribirse de forma explícita.

La entrega es asíncrona — los eventos se procesan por lotes a través del pipeline de uso, así que espera demoras de segundos respecto a la llamada original a POST /usage/events. La clave de idempotencia es el ID del evento de uso, por lo que los reintentos nunca duplican.

Úsalo para reflejar el uso en tu propio almacén de analítica sin hacer polling.