Webhooks - ascii

Box webhooks send account-wide lifecycle events to your HTTPS endpoint. Use them to start work when a Box is usable, respond to provisioning failures, or continue an automation after a Box stops.

	CLI	API	SDKs	Dashboard
Register	`box webhook create`	`POST /webhooks`	`createWebhook`	Webhooks
List / read	`box webhook list`	`GET /webhooks`, `GET /webhooks/{id}`	`listWebhooks`, `getWebhook`	Webhooks
Edit in place	not available	`PATCH /webhooks/{id}`	`updateWebhook`	not available
Rotate secret	`box webhook rotate`	`POST /webhooks/{id}/rotate`	`rotateWebhookSigningSecret`	Webhooks
Remove	`box webhook remove`	`DELETE /webhooks/{id}`	`deleteWebhook`	Webhooks
Delivery history	not available	not available	not available	Webhooks → Deliveries

Register an endpoint

box webhook create https://example.com/hooks/box \
  --name production \
  --event ready \
  --event error \
  --event archived

curl -sS -X POST "$BOX_API_BASE/webhooks" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "url": "https://example.com/hooks/box",
    "events": ["box.ready", "box.error", "box.archived"]
  }'

const created = await box.createWebhook({
  webhookCreateRequest: {
    name: "production",
    url: "https://example.com/hooks/box",
    events: new Set(["box.ready", "box.error", "box.archived"]),
  },
});
console.log(created.webhook.id, created.secret);   // secret is shown once

from ascii_box_sdk.models.webhook_create_request import WebhookCreateRequest

created = box.create_webhook(WebhookCreateRequest(
    name="production",
    url="https://example.com/hooks/box",
    events=["box.ready", "box.error", "box.archived"],
))
print(created.webhook.id, created.secret)   # secret is shown once

The CLI’s --event accepts ready, error, or archived with or without the box. prefix, and subscribes to all three when you omit it. The API and SDKs take the full box. form and require at least one event. The call returns a signing secret beginning with whsec_. It is shown only once. Store it in your secret manager.

Endpoints must use HTTPS on port 443 and resolve only to public IP addresses. Redirects are not followed. An account can register up to 10 endpoint URLs.

Manage endpoints

box webhook list
box webhook rotate <id>   # replaces the signing secret
box webhook remove <id>

curl -sS "$BOX_API_BASE/webhooks" \
  -H "Authorization: Bearer $BOX_API_KEY"

curl -sS "$BOX_API_BASE/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $BOX_API_KEY"

curl -sS -X PATCH "$BOX_API_BASE/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["box.error"]}'

curl -sS -X POST "$BOX_API_BASE/webhooks/$WEBHOOK_ID/rotate" \
  -H "Authorization: Bearer $BOX_API_KEY"

curl -sS -X DELETE "$BOX_API_BASE/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $BOX_API_KEY"

await box.listWebhooks();
await box.getWebhook({ webhookId: "wh_0123456789abcdef01234567" });

await box.updateWebhook({
  webhookId: "wh_0123456789abcdef01234567",
  webhookUpdateRequest: { events: new Set(["box.error"]) },
});

const rotated = await box.rotateWebhookSigningSecret({
  webhookId: "wh_0123456789abcdef01234567",
});
console.log(rotated.secret);

await box.deleteWebhook({ webhookId: "wh_0123456789abcdef01234567" });

from ascii_box_sdk.models.webhook_update_request import WebhookUpdateRequest

box.list_webhooks()
box.get_webhook("wh_0123456789abcdef01234567")

box.update_webhook(
    "wh_0123456789abcdef01234567",
    WebhookUpdateRequest(events=["box.error"]),
)

rotated = box.rotate_webhook_signing_secret("wh_0123456789abcdef01234567")
print(rotated.secret)

box.delete_webhook("wh_0123456789abcdef01234567")

The Webhooks tab of the dashboard does the same, and is the only surface that shows delivery history.

Only the API and SDKs can change an existing endpoint’s name, URL, or events in place (PATCH /webhooks/{webhookId}). The CLI and the dashboard have no edit: delete and re-create, which mints a new signing secret.

During rotation, accept both the old and new secret briefly: an attempt already in flight can still carry the old signature. Deleting an endpoint removes queued deliveries, but an attempt already in flight can still arrive.

Events

Event	Sent when
`box.ready`	A Box enters a usable state (`ready`, `idle`, or `running`) after being non-usable, including recovery from an error.
`box.error`	A Box enters `error`.
`box.archived`	A Box finishes stopping and enters `archived`.

Each state transition creates one immutable event per subscribed endpoint in the same database transaction as the state change.

Payload

{
  "id": "evt_2af97cd17a8248bb8fe37653a235bc91",
  "type": "box.ready",
  "createdAt": "2026-08-11T12:00:00.000Z",
  "data": {
    "box": {
      "id": "bx_23456789",
      "name": "Production worker"
    },
    "previousState": "cloning",
    "state": "ready"
  }
}

The public Box ID is in data.box.id. Use the top-level event id as an idempotency key.

Verify signatures

Every request includes:

Header	Value
`X-Ascii-Event`	Event type
`X-Ascii-Delivery`	Stable event ID
`X-Ascii-Timestamp`	Unix timestamp for this attempt
`X-Ascii-Signature`	`v1=` followed by a hex HMAC-SHA256 signature
`X-Ascii-Attempt`	Attempt number, starting at 1

Compute the expected signature over the exact raw request body:

HMAC_SHA256(secret, delivery_id + "." + timestamp + "." + raw_body)

Compare signatures in constant time, reject stale timestamps, and deduplicate the delivery ID.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody: Buffer, headers: Headers, secret: string) {
  const id = headers.get("x-ascii-delivery") ?? "";
  const timestamp = headers.get("x-ascii-timestamp") ?? "";
  const supplied = (headers.get("x-ascii-signature") ?? "").replace(/^v1=/, "");
  const expected = createHmac("sha256", secret)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  const issuedAt = Number(timestamp);
  if (!Number.isFinite(issuedAt) || Math.abs(Date.now() / 1000 - issuedAt) > 300) return false;
  if (!/^[a-f0-9]{64}$/i.test(supplied)) return false;
  return timingSafeEqual(Buffer.from(supplied, "hex"), Buffer.from(expected, "hex"));
}

import hmac, re, time
from hashlib import sha256

def verify_webhook(raw_body: bytes, headers, secret: str) -> bool:
    delivery = headers.get("x-ascii-delivery", "")
    timestamp = headers.get("x-ascii-timestamp", "")
    supplied = headers.get("x-ascii-signature", "").removeprefix("v1=")

    try:
        if abs(time.time() - float(timestamp)) > 300:
            return False
    except ValueError:
        return False
    if not re.fullmatch(r"[a-fA-F0-9]{64}", supplied):
        return False

    expected = hmac.new(
        secret.encode(),
        f"{delivery}.{timestamp}.".encode() + raw_body,
        sha256,
    ).hexdigest()
    return hmac.compare_digest(supplied.lower(), expected)

Verify the raw bytes before parsing JSON. Re-serializing the body changes the signature.

Delivery and retries

A 2xx response marks the event delivered. Other responses, connection failures, or the 5-second timeout retry with exponential backoff for up to 8 attempts. Delivery is at least once, so the same event ID can arrive more than once. Separate events can arrive out of order; use each event’s ID, creation time, and state rather than assuming request order. Return a 2xx quickly and move slow work to your own queue. Completed and exhausted delivery records are retained for 30 days.

Inspect deliveries

Open Webhooks in the Box dashboard, then expand Deliveries beside an endpoint. The recent-delivery log shows what fired, the exact payload, Box and event IDs, attempt count, HTTP result or connection diagnostic, and the next retry time when applicable.

​Register an endpoint

​Manage endpoints

​Events

​Payload

​Verify signatures

​Delivery and retries

​Inspect deliveries

Register an endpoint

Manage endpoints

Events

Payload

Verify signatures

Delivery and retries

Inspect deliveries