Payload

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

subscriptionIdstring

The subscription ID.

customerIdstring

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

currentBalancenumber

The balance after depletion in rate scale. Zero, or negative when overage is allowed.

currencystring

The subscription currency.

{
  "event": "balance.depleted",
  "timestamp": "2026-06-22T17:45:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "currentBalance": 0,
    "currency": "usd"
  }
}

Cuándo se dispara

El procesador asíncrono de uso dispara este evento una vez cuando una deducción lleva el saldo prepago de positivo a cero o por debajo. En planes que bloquean al agotarse, el uso posterior se rechaza con insufficient_balance; de lo contrario, el saldo queda en negativo y el uso continúa.

customer.state_changed se dispara junto a él con el trigger balance_depleted.

Úsalo para cortar las funciones restringidas o impulsar un flujo de recarga urgente.