wallet.low_balance

Summary

wallet.low_balance fires when a wallet debit brings the balance below the workspace's configured alert threshold. It is emitted at most once per threshold-crossing event; subsequent debits while already below the threshold do not re-fire until the balance recovers above the threshold and drops again.

This event is subscribable via workspace webhooks (POST /v1/webhooks).

Payload

{
  "kind": "wallet.low_balance",
  "event_id": "01900000-0000-7000-8000-000000000001",
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "occurred_at": "2026-06-27T10:00:00.000Z",
  "data": {
    "balance_minor": 4800,
    "currency": "KES",
    "threshold_minor": 5000
  }
}

Headers

Every webhook delivery includes the following request headers:

Delivery semantics

• At-least-once: The dispatcher may deliver the same event more than once. Deduplicate using event_id or the X-Sautikit-Idempotency-Key header.
• Retry schedule: Up to 5 attempts with exponential backoff (1-2-4-8-16 seconds). After exhausting attempts the delivery row moves to dead_letter.
• Timeout: Your endpoint must respond within 10 seconds. A non-2xx response or timeout counts as a failed attempt.

Example handler

import { createHmac } from "node:crypto";
 
export async function POST(req) {
  const sig = req.headers["x-sautikit-signature"];
  const body = await req.text();
  const expected = createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(body)
    .digest("hex");
  if (sig !== expected) return new Response("Forbidden", { status: 403 });
 
  const event = JSON.parse(body);
  if (event.kind === "wallet.low_balance") {
    const { balance_minor, currency, threshold_minor } = event.data;
    console.warn(`Low balance: ${balance_minor / 100} ${currency} (threshold: ${threshold_minor / 100})`);
    // trigger top-up, send Slack alert, page on-call...
  }
  return new Response("OK", { status: 200 });
}

Next steps

• Subscribe via POST /v1/webhooks with events: ["wallet.low_balance"].
• Configure alert email subscribers via POST /v1/wallet/alert/subscribers.
• Pair with wallet.top_up to clear alerts when funds are replenished.