Appearance

Sandbox Lifecycle Events ​

SandBase emits lifecycle events whenever a sandbox changes state. You can consume them two ways:

  • Events API — poll the latest events for a sandbox or for your whole org.
  • Webhooks — receive real-time POST callbacks when events occur.

Both are E2B-compatible.

Event types ​

TypeEmitted when
sandbox.lifecycle.createdA sandbox is created
sandbox.lifecycle.updatedA sandbox's configuration changes (e.g. timeout updated)
sandbox.lifecycle.pausedA sandbox is paused
sandbox.lifecycle.resumedA paused sandbox is resumed
sandbox.lifecycle.killedA sandbox is terminated

Roadmap

sandbox.lifecycle.snapshotted is reserved for compatibility but not yet emitted, since snapshots are on the roadmap.

Events API ​

List events for a sandbox ​

bash
curl https://api.sandbase.ai/events/sandboxes/SANDBOX_ID \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

List events for your org ​

bash
curl "https://api.sandbase.ai/events/sandboxes?limit=10" \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Example response:

json
[
  {
    "id": "evt_01abc...",
    "type": "sandbox.lifecycle.killed",
    "sandboxId": "sbx_01J8XYZ",
    "sandboxTemplateId": "code_interpreter",
    "timestamp": "2026-05-29T10:05:00Z"
  },
  {
    "id": "evt_02def...",
    "type": "sandbox.lifecycle.created",
    "sandboxId": "sbx_01J8XYZ",
    "sandboxTemplateId": "code_interpreter",
    "timestamp": "2026-05-29T10:00:00Z"
  }
]
Query parameterDescription
limitMaximum number of events to return

Webhooks ​

Webhooks deliver lifecycle events to an external endpoint in real time, so you don't have to poll.

Register a webhook ​

bash
curl -X POST https://api.sandbase.ai/webhooks \
  -H "Authorization: Bearer sk-sb-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Sandbox Webhook",
    "url": "https://your-endpoint.com/webhook",
    "enabled": true,
    "events": ["sandbox.lifecycle.created", "sandbox.lifecycle.killed"],
    "signatureSecret": "secret-for-signature-verification"
  }'
FieldTypeRequiredDescription
namestring✅Human-readable webhook name
urlstring✅HTTPS endpoint that receives event POSTs
eventsstring[]✅Event types to subscribe to
enabledboolean❌Whether the webhook is active (default true)
signatureSecretstring❌Secret used to sign payloads for verification

List webhooks ​

bash
curl https://api.sandbase.ai/webhooks \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Delete a webhook ​

bash
curl -X DELETE https://api.sandbase.ai/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Webhook payload ​

When an event fires, your endpoint receives a POST with a JSON body:

json
{
  "id": "evt_01abc...",
  "type": "sandbox.lifecycle.killed",
  "sandboxId": "sbx_01J8XYZ",
  "sandboxTemplateId": "code_interpreter",
  "timestamp": "2026-05-29T10:05:00Z"
}

Verifying the signature ​

If you set a signatureSecret, each request includes a signature header so you can verify the payload originated from SandBase and wasn't tampered with. The signature is the base64-encoded SHA-256 hash of secret + rawBody (trailing = padding stripped).

python
import hashlib, base64

def verify(secret: str, payload: str, signature: str) -> bool:
    digest = hashlib.sha256((secret + payload).encode()).digest()
    expected = base64.b64encode(digest).decode().rstrip("=")
    return expected == signature
javascript
import crypto from 'node:crypto'

function verify(secret, payload, signature) {
  const expected = crypto
    .createHash('sha256')
    .update(secret + payload)
    .digest('base64')
    .replace(/=+$/, '')
  return expected === signature
}

Next steps ​