> ## Documentation Index
> Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# balance.alert

> Fired the moment your balance crosses the alert threshold

## Event: `balance.alert`

Sent immediately when your partner balance crosses below the configured alert threshold. Unlike [`balance.low`](/partner/webhooks/balance-low) (a daily check), this event is evaluated after every settlement and balance change, and fires **exactly once per downward crossing** — it re-arms only after your balance recovers above the threshold.

See [balance thresholds](/partner/balance#balance-thresholds) for the full threshold model, including the issuance-block and card-freeze safety levels.

## Payload

```json theme={null}
{
  "balance": 5000,
  "threshold": 10000,
  "currency": "USD"
}
```

| Field | Type | Description |
| - | - | - |
| `balance` | number | Current balance in minor units (cents) |
| `threshold` | number | Alert threshold in minor units (cents) |
| `currency` | string | ISO 4217 currency code |

## Response

Your endpoint must return a **2xx** status code within **30 seconds** to acknowledge receipt. Any non-2xx response or timeout triggers the [retry policy](/partner/webhooks#retry-policy).

| Status code | Meaning |
| - | - |
| `200` | Event received and processed |
| `202` | Event received, will process asynchronously |
| Any non-2xx | Delivery failed — will retry |

## Example handler

```javascript theme={null}
app.post("/webhooks/contro", (req, res) => {
  const eventType = req.headers["x-contro-event"];

  if (eventType === "balance.alert") {
    const { balance, threshold, currency } = req.body;
    // Top up promptly — further thresholds can block issuance or freeze cards
  }

  res.status(200).send("OK");
});
```