storage.tier_changed

Fires when the workspace recording storage tier is upgraded or downgraded.

2026-06-27

storage.tier_changed fires when the workspace recording storage tier changes, either an upgrade (paid via wallet debit) or a downgrade. Note that downgrades are not refunded and take effect immediately. Use this event to update your own billing records or notify workspace members.

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

{
  "kind": "storage.tier_changed",
  "event_id": "01900000-0000-7000-8000-000000000001",
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "occurred_at": "2026-06-27T10:00:00.000Z",
  "data": {
    "previous_tier_gb": 5,
    "new_tier_gb": 25,
    "direction": "upgrade",
    "effective_at": "2026-06-27T10:00:00.000Z"
  }
}

Allowed tier_gb values: 5, 10, 25, 50, 100, 250. 5 is the free tier.

Every webhook delivery includes the following request headers:

Header	Description
`X-Sautikit-Signature`	HMAC-SHA256 of the raw body, hex-encoded. Verify with your subscription secret.
`X-Sautikit-Idempotency-Key`	Unique delivery ID for deduplication.
`X-Sautikit-Event`	Literal event kind: `storage.tier_changed`.

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.

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 === "storage.tier_changed") {
    const { previous_tier_gb, new_tier_gb, direction } = event.data;
    console.log(`Storage tier ${direction}: ${previous_tier_gb}GB -> ${new_tier_gb}GB`);
    // update subscription records, notify admins...
  }
  return new Response("OK", { status: 200 });
}

Subscribe via POST /v1/webhooks with events: ["storage.tier_changed"].
See Storage API for tier management endpoints.
See Webhook concepts for signature verification details.

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

{
  "kind": "storage.tier_changed",
  "event_id": "01900000-0000-7000-8000-000000000001",
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "occurred_at": "2026-06-27T10:00:00.000Z",
  "data": {
    "previous_tier_gb": 5,
    "new_tier_gb": 25,
    "direction": "upgrade",
    "effective_at": "2026-06-27T10:00:00.000Z"
  }
}

Allowed tier_gb values: 5, 10, 25, 50, 100, 250. 5 is the free tier.

Header

Description

X-Sautikit-Signature

HMAC-SHA256 of the raw body, hex-encoded. Verify with your subscription secret.

X-Sautikit-Idempotency-Key

Unique delivery ID for deduplication.

X-Sautikit-Event

Literal event kind: storage.tier_changed.

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.

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 === "storage.tier_changed") {
    const { previous_tier_gb, new_tier_gb, direction } = event.data;
    console.log(`Storage tier ${direction}: ${previous_tier_gb}GB -> ${new_tier_gb}GB`);
    // update subscription records, notify admins...
  }
  return new Response("OK", { status: 200 });
}