---
title: "Balance events"
method: POST
path: "balanceEvent"
tags: ["Webhooks"]
---

# Balance events

`POST balanceEvent` (webhook)

Sent when your available balance is $1.00 or less, or below $0.50, to each enabled webhook that lists the event, from a check about once a minute.
balance.low: the available balance is between $0.50 and $1.00; it is sent again only after the balance has gone back above $2.00. balance.depleted: the available balance is below $0.50 and running workloads are being stopped. A balance that falls from above $1.00 to below $0.50 between two checks sends balance.depleted alone.
The check covers an organization with a VM or pod running, with auto-recharge on, or with compute usage not yet billed. A balance-exempt organization gets neither event, and a check that starts an auto-recharge sends neither. Listing a balance event needs billing read access.

## Headers

- `X-OpenRelay-Signature` string, required
- `X-OpenRelay-Event` string, required
- `X-OpenRelay-Delivery` string, uuid, required
- `User-Agent` 'OpenRelay-Webhook/1.0', required
- `X-VectorLay-Signature` string, required
- `X-VectorLay-Event` string, required
- `X-VectorLay-Delivery` string, uuid, required

## Payload

- BalanceWebhookEvent: The body of a balance.low or balance.depleted delivery.
  - `created_at` string, date-time, required: When the event was recorded, RFC 3339 in UTC to the second.
  - `data` object, required
    - `available_cents` integer, required: The available balance, in cents. It can be negative: usage keeps accruing between checks.
    - `threshold_cents` integer, required: The line it crossed, in cents, 100 for balance.low and 50 for balance.depleted.
  - `id` string, required: The event's id, evt_ followed by a UUID, new each time an event is recorded. A retry of a delivery carries the same id.
  - `type` 'balance.low' | 'balance.depleted', required

## Acknowledgement `2XX`

Delivered. Any 2xx status within 10 seconds counts, and its body is not kept.

## Other responses

- `default`: Any other final status, a connection error, or no answer within 10 seconds fails the attempt, and up to the first 1000 bytes of the response body are kept in the delivery's error message. Redirects are followed, at most 9 (10 requests in all), each hop held to the webhook URL's rules (https, no credentials, no internal address), and the last status counts. A failed delivery is tried at most 3 times: the second attempt about 10 seconds after the first and the third about 60 seconds after the second, each run by a scheduler that checks every 30 seconds, so a retry can come up to 30 seconds later. A retry that comes due while the webhook is disabled or deleted is dropped.

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)