number.released

Sent when a phone number is released from the workspace.

2026-06-27

number.released is sent when a number leaves your workspace: you released it, a trial number ended, or its monthly rental stayed unpaid. Calls to the number stop reaching you from this point.

Subscribe by adding number.released to the events of a webhook created with POST /v1/webhooks.

The body is flat JSON. The event name is in the X-Sautikit-Event-Kind header, not in the body.

{
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "number_id": "01900000-0000-7000-8000-000000000004",
  "e164": "+254720000000",
  "released_at": "2026-06-27T10:00:00.123456789Z"
}

Field	Type	Description
`workspace_id`	string (UUID)	The workspace the number left.
`number_id`	string (UUID)	The number's id.
`e164`	string	The number in E.164 form.
`released_at`	string (RFC 3339)	When the number was released.
`reason`	string	`rental_past_due` when the number was released for unpaid rental. Absent otherwise.

Header	Description
`X-Sautikit-Event-Kind`	`number.released`. Route on this.
`X-Sautikit-Event-Id`	UUID of the event. Deduplicate on this.
`X-Sautikit-Delivery-Id`	UUID of this delivery.
`X-Sautikit-Attempt`	Attempt number, starting at `1`.
`X-Sautikit-Timestamp`	Unix time (seconds) when the delivery was signed.
`X-Sautikit-Signature`	`t=<timestamp>,v1=<hex HMAC-SHA256>`. See Verify webhook signatures.

At least once. The same event can arrive more than once. Deduplicate on the X-Sautikit-Event-Id header.
Retries. Up to 8 attempts, waiting 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours and 24 hours between them. After the 8th failed attempt the delivery is not tried again.
Timeout. Respond with a 2xx status within 10 seconds. Anything else counts as a failed attempt.

// verifyWebhook is the function from the "Verify webhook signatures" guide.
import { verifyWebhook } from "./verify-webhook.js";
 
export async function POST(req) {
  const body = await req.text();
  try {
    verifyWebhook(body, req.headers.get("x-sautikit-signature") ?? "", process.env.WEBHOOK_SECRET);
  } catch {
    return new Response("Forbidden", { status: 403 });
  }
 
  if (req.headers.get("x-sautikit-event-kind") === "number.released") {
    const { e164, reason } = JSON.parse(body);
    console.log(`Number ${e164} released${reason ? ` (${reason})` : ""}`);
    // remove it from your routing tables and records
  }
  return new Response("OK", { status: 200 });
}

The body is flat JSON. The event name is in the X-Sautikit-Event-Kind header, not in the body.

{
  "workspace_id": "01900000-0000-7000-8000-000000000002",
  "number_id": "01900000-0000-7000-8000-000000000004",
  "e164": "+254720000000",
  "released_at": "2026-06-27T10:00:00.123456789Z"
}

Field

Type

Description

workspace_id

string (UUID)

The workspace the number left.

number_id

string (UUID)

The number's id.

e164

string

The number in E.164 form.

released_at

string (RFC 3339)

When the number was released.

reason

string

rental_past_due when the number was released for unpaid rental. Absent otherwise.

Header

Description

X-Sautikit-Event-Kind

number.released. Route on this.

X-Sautikit-Event-Id

UUID of the event. Deduplicate on this.

X-Sautikit-Delivery-Id

UUID of this delivery.

X-Sautikit-Attempt

Attempt number, starting at 1.

X-Sautikit-Timestamp

Unix time (seconds) when the delivery was signed.

X-Sautikit-Signature

t=<timestamp>,v1=<hex HMAC-SHA256>. See Verify webhook signatures.

At least once. The same event can arrive more than once. Deduplicate on the X-Sautikit-Event-Id header.

Retries. Up to 8 attempts, waiting 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours and 24 hours between them. After the 8th failed attempt the delivery is not tried again.

Timeout. Respond with a 2xx status within 10 seconds. Anything else counts as a failed attempt.

// verifyWebhook is the function from the "Verify webhook signatures" guide.
import { verifyWebhook } from "./verify-webhook.js";
 
export async function POST(req) {
  const body = await req.text();
  try {
    verifyWebhook(body, req.headers.get("x-sautikit-signature") ?? "", process.env.WEBHOOK_SECRET);
  } catch {
    return new Response("Forbidden", { status: 403 });
  }
 
  if (req.headers.get("x-sautikit-event-kind") === "number.released") {
    const { e164, reason } = JSON.parse(body);
    console.log(`Number ${e164} released${reason ? ` (${reason})` : ""}`);
    // remove it from your routing tables and records
  }
  return new Response("OK", { status: 200 });
}