Usage Alert Triggered

Fired when a customer crosses a configured usage alert threshold.

WEBHOOK balances.usage_alert_triggered

Example

{
  "type": "balances.usage_alert_triggered",
  "data": {
    "customer_id": "org_123",
    "feature_id": "api_calls",
    "entity_id": "workspace_abc",
    "usage_alert": {
      "name": "80% usage warning",
      "threshold": 80,
      "threshold_type": "usage_percentage",
      "basis": "balance"
    },
    "balance": {
      "usage": 1600,
      "granted": 2000,
      "included": 2000,
      "remaining": 400
    }
  }
}

Payload Fields

customer_id · string

The ID of the customer whose usage alert was triggered.

feature_id · string

The feature ID the alert applies to.

entity_id · string

The entity ID the alert applies to, if the usage was entity-scoped.

usage_alert · object

Details of the usage alert that was triggered.

Show properties

name · string

User-defined label for the alert, if provided.

threshold · number · required

The threshold value that was crossed.

threshold_type · 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage' · required

Whether the threshold is an absolute usage count or a percentage.

basis · 'balance' | 'included' | 'recurring' · required

What 100% meant for this alert.

balance · object

The balance the alert measured.

Show properties

usage · number · required

Units consumed on the feature, after this event.

granted · number · required

Every grant on the feature: included, prepaid and rollover.

included · number · required

Grants from plan allowances only.

remaining · number · required

The alert’s denominator minus usage. Clamped at zero for included and recurring; balance can go negative on overage.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

type · string · required

The webhook event type.

Allowed value: "balances.usage_alert_triggered"

data · object · required

Option 1

Option 2

Show child attributes

Example:

{
  "customer_id": "org_123",
  "feature_id": "api_calls",
  "entity_id": "workspace_abc",
  "usage_alert": {
    "name": "80% usage warning",
    "threshold": 80,
    "threshold_type": "usage_percentage",
    "basis": "balance"
  },
  "balance": {
    "usage": 1600,
    "granted": 2000,
    "included": 2000,
    "remaining": 400
  }
}

Response

200

Webhook received successfully.