Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
API ReferenceComputeWebhooks

Balance events

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.

Header Parameters

X-OpenRelay-Signature*string

sha256= followed by the lowercase hex HMAC-SHA256 of the raw request body. The HMAC key is the 64 character lowercase hex SHA-256 of your whole whsec_ secret, prefix included, used as those characters rather than decoded from hex. Verify it over the exact bytes received, before parsing them. Only the body is signed: there is no timestamp. The signing secret is read at each attempt, so a retry after a regenerate is signed with the new secret.

Match^sha256=[0-9a-f]{64}$
X-OpenRelay-Event*string

The event's type, the same as the body's type.

X-OpenRelay-Delivery*string

The id of this delivery to this webhook, a UUID. Every retry of the delivery carries the same id and the same body, so deduplicate on it.

Formatuuid
User-Agent*"OpenRelay-Webhook/1.0"
Value in"OpenRelay-Webhook/1.0"
X-VectorLay-Signature*stringDeprecated

The same value as X-OpenRelay-Signature, under the name used before OpenRelay. Deprecated, to be removed in a future release: verify X-OpenRelay-Signature.

Match^sha256=[0-9a-f]{64}$
X-VectorLay-Event*stringDeprecated

The same value as X-OpenRelay-Event. Deprecated, to be removed in a future release: read X-OpenRelay-Event.

X-VectorLay-Delivery*stringDeprecated

The same value as X-OpenRelay-Delivery. Deprecated, to be removed in a future release: read X-OpenRelay-Delivery.

Formatuuid

Request Body

application/json
  1. body

The body of a balance.low or balance.depleted delivery.

id*string

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*string
Value in"balance.low""balance.depleted"
created_at*string

When the event was recorded, RFC 3339 in UTC to the second.

Formatdate-time
data*

Response Body

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

Example Requests
POST/balanceEvent

The body of a balance.low or balance.depleted delivery.

Request Body
application/json
{  "id": "evt_…",  "type": "balance.low",  "created_at": "2026-06-10T12:00:00Z",  "data": {    "available_cents": 80,    "threshold_cents": 100  }}
Header Parameters
{  "X-OpenRelay-Signature": "string",  "X-OpenRelay-Event": "string",  "X-OpenRelay-Delivery": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "User-Agent": "OpenRelay-Webhook/1.0",  "X-VectorLay-Signature": "string",  "X-VectorLay-Event": "string",  "X-VectorLay-Delivery": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}