Skip to main content
Webhooks push sandbox events to your server as they happen, so an agent orchestrator does not poll GET /sandbox/{id}/status in a loop waiting for a pod to come up or a command to finish.

Events

Sandbox lifecycle Command execution Files and artifacts Checkpoints Resources and security

Subscribe

Subscribe to specific events, or to "*" for all of them. Give a secret — it is what lets you verify that a delivery came from StateSet rather than from anyone who learned your URL.

The payload

Every delivery has the same envelope; data is event-specific.
id is unique per delivery and stable across retries — use it to make your handler idempotent, because a retry after a timeout means you may see the same delivery twice.

Verify the signature

When a subscription has a secret, every delivery carries an HMAC-SHA256 of the raw body in the X-Webhook-Signature header, as sha256=<hex>. Verify it against the raw request body, not a re-serialised object — whitespace differences change the digest.
Compare with a constant-time function — timingSafeEqual, hmac.compare_digest, hmac.Equal — not ==. A plain string comparison leaks how many leading bytes matched.