Documentation

Sandbox lifecycle webhooks

Webhooks provide a way for notifications to be delivered to an external web server whenever certain sandbox lifecycle events occur. This allows you to receive real-time updates about sandbox creation, updates, and termination without having to poll the API. All webhook requests require authentication using your team API key.

Webhook management

Register webhook

Register a new webhook to receive sandbox lifecycle events. The webhook will be registered for the team ID associated with your API key. You will receive webhook notifications for sandbox lifecycle events from sandboxes created by your team with the following payload.

// Register a new webhook
const resp = await fetch(
  'https://api.e2b.app/events/webhooks/sandboxes',
  {
    method: 'POST',
    headers: {
      'X-API-Key': E2B_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://your-webhook-endpoint.com/webhook',
      events: ['create', 'kill', 'update']
    }),
  }
)

if (resp.status === 201) {
  console.log('Webhook registered successfully')
}

Get webhook configuration

Retrieve the current webhook configuration for your team.

// Get current webhook configuration
const resp = await fetch(
  'https://api.e2b.app/events/webhooks/sandboxes',
  {
    method: 'GET',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)
const webhookConfig = await resp.json()
console.log(webhookConfig)
// {
//   "teamID": "<your-team-id>",
//   "url": "https://your-webhook-endpoint.com/webhook",
//   "events": ["create", "kill"]
// }

Update webhook configuration

Update an existing webhook configuration. The update will replace the previous configuration fields with provided fields.

// Update webhook configuration
const resp = await fetch(
  'https://api.e2b.app/events/webhooks/sandboxes',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': E2B_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://your-updated-webhook-endpoint.com/webhook',
      events: ['create']
    }),
  }
)

const updatedWebhookConfig = await resp.json()
console.log(updatedWebhookConfig)
// {
//     "teamID": "<your-team-id>",
//     "events": ["create"],
//     "url": "https://your-updated-webhook-endpoint.com/webhook"
// }

Delete webhook

Unregister the webhook.

// Delete webhook configuration
const resp = await fetch(
  'https://api.e2b.app/events/webhooks/sandboxes',
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)

if (resp.status === 200) {
  console.log('Webhook deleted successfully')
}

Test webhook

Send a test webhook to verify your endpoint is working correctly.

// Test webhook endpoint
const resp = await fetch(
  'https://api.e2b.app/events/webhooks/sandboxes/test',
  {
    method: 'POST',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)

if (resp.status === 200) {
  console.log('Test webhook sent successfully')
}

Webhook payload

When a webhook is triggered, your endpoint will receive a POST request with a JSON payload containing the sandbox event data. The payload structure matches the event format from the API:

{
  "eventCategory": "lifecycle",
  "eventData": {
    "sandbox_metadata": {
      "<custom-key>": "<custom-value>"
    }
  },
  "eventLabel": "create",
  "sandboxBuildId": "a979a14b-bdcc-49e6-bc04-1189fc9fe7c2",
  "sandboxExecutionId": "1dae9a1c-9957-4ce7-a236-a99d5779aadf",
  "sandboxId": "<your-sandbox-id>",
  "sandboxTeamId": "<your-team-id>",
  "sandboxTemplateId": "rki5dems9wqfm4r03t7g",
  "timestamp": "2025-08-06T20:59:24Z"
}

Available event types

The following event types can be subscribed to via webhooks, they are used as the eventLabel field in the payload.

  • create - Sandbox creation
  • kill - Sandbox termination
  • update - Sandbox configuration updates
  • pause - Sandbox pausing
  • resume - Sandbox resuming