Skip to main content
Use the right record for the question: an operation tracks long-running work, an event reports a domain change, a webhook is an at-least-once delivery of an immutable event, usage is append-only metering, and audit records who attempted or completed a governed action.

​
Follow a durable operation

Every long mutation returns an operation with ID, sandbox ID, type, status, step, generation, attempt counters, deadline, retryability, compensation requirement, timestamps, and optional failure/result data.
Store the ID before waiting. A client timeout does not cancel or roll back server work. Refetch the operation, then the affected resource. If terminal status is not succeeded, surface the failure rather than returning a partial resource as success.

​
Consume sandbox events

Events use a versioned envelope:
The per-sandbox SSE stream is monotonic by sequence. Delivery is at least once, so consumers must deduplicate by event ID and commit their last fully processed sequence. On reconnect, pass after_sequence; after a gap, refetch current resource state. The catalog covers lifecycle/readiness, executions/processes, snapshots/volumes, policy application, and quota warnings/exceeded events. Do not infer a global ordering across sandboxes or endpoints.

​
Create and verify a webhook

Create endpoints only at HTTPS destinations. Subscribe to exact event types or supported prefixes such as sandbox.snapshot.*:
The signing secret is returned only at endpoint creation or explicit rotation. Verification must use the exact raw request bytes before JSON parsing. Official helpers validate HMAC-SHA256(timestamp + "." + rawBody), the v1= signature, constant-time equality, and a timestamp tolerance.
After verification:
  1. Reject events outside your accepted API versions/types.
  2. Deduplicate by event ID or delivery ID in durable storage.
  3. Enqueue work, then return a success response quickly.
  4. Make handlers idempotent because retries and manual replay can duplicate delivery.
  5. Never fetch a URL from event data without applying your own validation.

​
Delivery history and replay

GET /api/v1/webhook-deliveries filters by endpoint or sandbox. Detail includes status, attempt count, next retry, safe response excerpt, error code, and each attempt’s timing/status. States are pending, delivering, succeeded, and dead_letter. POST /api/v1/webhook-deliveries/{deliveryId}/replay requires an idempotency key and creates a new signed delivery attempt from the original immutable event. Replay is permission-controlled, rate-limited, and audited. It does not create a new domain event. Repeated failures may disable an endpoint. Fix TLS/DNS/response behavior, rotate a compromised signing secret, then explicitly re-enable according to policy.

​
Usage and quotas

GET /api/v1/usage accepts start, end, timezone, sandbox_id, and group_by (sandbox, project, team, profile, tag, or product_source). Records contain metric, quantity, unit, exact window, and safe metadata. GET /api/v1/usage/export returns server-generated CSV for the same filters. Billable meters can include reserved CPU seconds, reserved memory GB-seconds, active/sleeping disk GB-hours, snapshot/artifact storage, public egress, and optional execution/browser units. Price is separate from raw usage. Show an estimate only when the response provides an authoritative complete catalog, currency, and qualification; otherwise show units and quotas without inventing cost.

​
Audit history

GET /api/v1/audit-events is permission-controlled and cursor-paginated. Filter by actor, action, target type/ID, outcome, source, and time range. Audit entries record actor, action, target, outcome, source, request/correlation ID, and safe change metadata. Events and audit are not interchangeable: events drive resource integrations, while audit establishes accountable activity including denied or failed actions. Neither may contain secret plaintext, terminal tickets, signed URLs, or internal worker credentials.

API and SDKs

Review endpoint and client conventions.

Troubleshooting

Build a safe diagnostic bundle.