Sandbox webhooks and event delivery

Subscribe to current lifecycle, execution, process, recovery, and governance events and verify signatures over the exact request bytes.

Webhooks notify your receiver of events. A delivery is an observation to reconcile with its original sandbox/execution/process record, not permission to replay a mutation.

Subscribe

Use the controller’s canonical /api/v1/webhooks route with current credentials:

curl --fail-with-body --silent --show-error \
  "$STATESET_BASE_URL/api/v1/webhooks" \
  --header "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example.com/sandbox-events","events":["sandbox.ready","command.completed","process.exited"],"secret":"REPLACE_WITH_A_RANDOM_RECEIVER_SECRET","retry_count":3}'

Use an authorized write-scoped key and a reachable receiver. Retain the secret yourself; webhook responses strip it. Destination/DNS/private-network/redirect policy is enforced by server configuration and cannot be established from the registration response alone.

Current event families

Family	Examples in the reviewed source
Runtime	sandbox.created, ready, stopped, error, timeout, expiring, terminated
Pause/recovery	sandbox.paused, resumed, pause_failed, resume_failed, recovering, recovered, recovery_failed
Branches/snapshots	sandbox.forked, promoted, snapshot_created, snapshot_deleted
Execution/process	command.started, completed, failed; process.started, exited, restarted
Session	agent_session.started, stale, rotation_failed, completed, failed, suspended
Data	file.written, artifact uploaded/deleted, checkpoint created/restored/cloned/deleted
Policy/operations	Budget warning/exhausted, billing.suspended, agent.needs_human, progress, run finished/failed, security and resource events

This replaces the old fixed-count catalog. WEBHOOK_EVENTS in the deployed controller is the source of truth; not every event is emitted by every optional feature or version.

Signature contract

The JSON envelope includes id, event, timestamp, sandboxId, orgId, and data. Headers include X-Webhook-ID, X-Event-Type, and X-Delivery-ID. With a configured secret, X-Webhook-Signature is sha256= plus the hexadecimal HMAC-SHA256 of the raw JSON bytes. It is not an HMAC of a parsed/reformatted object or a timestamp-prefixed string.

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

export function verifySandboxWebhook(rawBody, signature, secret) {
  if (typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/.test(signature)) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature.slice(7), 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Preserve the original body before JSON middleware changes it. After verifying, parse/validate the envelope, deduplicate retained event/delivery identities, and apply your receiver’s recorded replay/freshness policy. A valid HMAC authenticates bytes, not an independent claim that the business task succeeded.

Delivery and reconciliation

Configured retry/time budgets and durable delivery records can produce repeated notifications; receivers must not perform duplicate external actions. Inspect failed/dead-letter deliveries through supported controller operations, retaining the original identities when investigating.

For live/replay output use authenticated SSE and its cursor contract rather than treating a webhook body as a complete stdout transcript. New metadata-only command/file/REPL audit records are a different surface and deliberately omit sensitive contents.

Source: Node webhook-manager.ts and webhook handlers, checked October 20, 2026. Continue with execution replay and operations/audit evidence.