number.released

Summary

number.released fires when a DID is unassigned from the workspace and returned to inventory. This can be triggered by an explicit release request, trial expiry termination, or an admin action. Use this event to clean up routing configuration, remove the number from internal phone books, and stop billing it in your own systems.

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

Payload

{
  "kind": "number.released",
  "event_id": "01900000-0000-7000-8000-000000000001",
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "occurred_at": "2026-06-27T10:00:00.000Z",
  "data": {
    "number_id": "01900000-0000-7000-8000-000000000003",
    "e164": "+254700000001",
    "country_code": "KE",
    "release_reason": "explicit",
    "released_at": "2026-06-27T10:00:00.000Z"
  }
}

Possible release_reason values: explicit (caller-initiated), trial_expired, admin_released.

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 === "number.released") {
    const { number_id, e164, release_reason } = event.data;
    console.log(`Number ${e164} released (${release_reason}): ${number_id}`);
    // remove from routing config, update CRM...
  }
  return new Response("OK", { status: 200 });
}

Next steps

• Subscribe via POST /v1/webhooks with events: ["number.released"].
• Pair with number.provisioned to track full number lifecycle.
• See Numbers API for release endpoint documentation.