Webhooks

Receive the lifecycle events of your sandboxes as HTTPS requests, signed with Standard Webhooks.

Overview

An endpoint is an HTTPS address of yours that LumiCloud calls with a POST request for each event it subscribes to. Endpoints belong to the account. They are managed in the console (Webhooks) or through the REST API at https://api.lumicloud.ai/v1/webhooks/. Deliveries are signed with Standard Webhooks (standardwebhooks.com), so the official libraries verify them.

E2B's webhook API (/events/webhooks) is not provided, and requests carry no e2b-signature. The body of a sandbox event keeps E2B's form, so code that reads E2B's lifecycle payload reads it unchanged; only the verification differs. E2B's events API (/events/sandboxes on api.lumicloud.dev) answers with your LumiBox API key.

Events

EventWhen
sandbox.lifecycle.createdA sandbox was created and started.
sandbox.lifecycle.pausedA sandbox was paused: its run ended and it can be resumed (event_data.pause_mode: full, or filesystem).
sandbox.lifecycle.resumedA paused sandbox was resumed (event_data.resume_mode: restore, or reboot from its file system).
sandbox.lifecycle.killedA sandbox was killed, timed out or lost: its run ended and it is gone (event_data.kill_reason says why).
sandbox.lifecycle.updatedA running sandbox's timeout or network was changed (event_data.set_timeout, network_egress); several in a run.
sandbox.lifecycle.checkpointedA snapshot of a running sandbox was taken and it went on running; several in a run.

An endpoint subscribes to event types or to a prefix ending in .* (sandbox.lifecycle.*, sandbox.*). Each type's example is under Examples, the schema of the body under JSON Schema.

Delivery

  • An event is sent about a second after it happens. If the cluster's real-time record misses it, the platform's reconciliation sends it within about two minutes.
  • Each event is delivered at least once. webhook-id is the event's ID, the same for every attempt and resend: a receiver drops what it has seen.
  • Order between events is not guaranteed; a retry can arrive after a later event. The timestamp in the body orders them.
  • A response with a status 2xx is a success. Anything else is a failure: another status, a redirect (not followed), no answer within 15 seconds, a failed connection or TLS handshake, a name that does not resolve.
  • A failed delivery is retried after 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours (each wait ±10%): 10 attempts over about three days. Retry-After on a failed answer lengthens the next wait, up to an hour.
  • After 5 failures in a row the endpoint rests: nothing is sent for a minute, then one delivery is tried; each further failure doubles the rest, up to an hour. Resting uses no attempts.
  • 410 Gone disables the endpoint at once; its pending deliveries are canceled.
  • A paused endpoint keeps its events and receives them when it is active again, within a delivery's deadline (about three days). A disabled endpoint receives nothing.
  • A delivery that used all its attempts is marked failed; Resend sends it again with the same event ID.
  • A new endpoint receives the events that happen after it is made, not earlier ones.

Request headers

HeaderValue
content-typeapplication/json
user-agentLumiCloud-Webhooks/1
webhook-idThe event's ID, the same for every attempt and resend.
webhook-timestampWhen the request was signed, in Unix seconds.
webhook-signaturev1,<signature>, one for each secret that signs now, separated by spaces.
lumi-delivery-idThe delivery (this event to this endpoint).
lumi-attemptThe attempt's number, from 1.
lumi-testtrue on an example sent from the console or the API.

Verifying a delivery

Use the raw body exactly as received, not a re-serialised one. The signature is the base64 of HMAC-SHA256, keyed with the secret's key, of webhook-id, a dot, webhook-timestamp, a dot and the body. The official libraries check it and refuse a timestamp more than five minutes away.

python# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

wh = Webhook("whsec_...")  # the endpoint's signing secret

def handle(raw_body: bytes, headers: dict):
    event = wh.verify(raw_body, headers)  # raises on a bad signature or an old timestamp
    if seen(headers["webhook-id"]):
        return 200
    ...
js// npm install standardwebhooks
import { Webhook } from "standardwebhooks"

const wh = new Webhook("whsec_...") // the endpoint's signing secret

app.post("/hooks", express.raw({ type: "application/json" }), (req, res) => {
  const event = wh.verify(req.body, req.headers) // throws on a bad signature or an old timestamp
  res.sendStatus(200)
})

Libraries for Go, Ruby, PHP, Java, Rust, C# and Elixir are listed on standardwebhooks.com.

Payload

The body of a sandbox event is JSON in the form of E2B's lifecycle webhooks (version v2, snake_case). event_data is the cluster's own: what it holds depends on the type.

json{
  "version": "v2",
  "id": "5b2c8e0e-8f0e-4a39-9c47-0d6a4c1f2a10",
  "type": "sandbox.lifecycle.killed",
  "timestamp": "2026-11-22T10:15:30.123456Z",
  "event_category": "lifecycle",
  "event_label": "kill",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e",
  "sandbox_template_id": "base",
  "sandbox_build_id": "7e3f1a52-4c1d-4e8a-b5a0-9f2b6c1d3e44",
  "sandbox_team_id": "3a1f0c52-6b7e-5d3a-8f10-2c4e9b7a1d05",
  "events_ttl_days": 30,
  "event_data": {
    "sandbox_metadata": { "user": "42" },
    "execution": { "started_at": "2026-11-22T10:10:00Z", "vcpu_count": 2, "memory_mb": 1024, "execution_time": 330123 },
    "kill_reason": "request"
  }
}
FieldMeaning
idThe event's ID (also webhook-id).
type, event_category, event_labelThe event type; lifecycle; create, pause, resume, kill, update or checkpoint.
timestampWhen the event happened (UTC, RFC 3339).
sandbox_id, sandbox_execution_idThe sandbox, and the run it was in (a resume starts a new run).
sandbox_template_id, sandbox_build_id, sandbox_team_idThe template and build the sandbox started from, and your account's team ID.
events_ttl_daysHow many days the event is kept and available from the events API.
event_data.sandbox_metadataThe metadata given when the sandbox was created, as given.
event_data.executionOn paused and killed events: started_at, vcpu_count, memory_mb of the run, and execution_time in milliseconds.
event_data.kill_reasonOn killed events, see below.
event_data.pause_mode, resume_modeOn paused and resumed events: how the sandbox was paused or resumed.
event_data.set_timeout, network_egressOn updated events: the new timeout or network settings.
event_data.platformSuspendedOn paused and killed events while the platform had stopped the account: arrears, freeze, operator, account or risk.

Examples

One example of each type, as delivered. event_data holds only what the cluster tells for that type.

sandbox.lifecycle.created

json{
  "version": "v2",
  "id": "a99ed186-49dc-5ea6-ab62-94369212e3da",
  "type": "sandbox.lifecycle.created",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "create",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "sandbox_metadata": {
      "user": "example"
    }
  }
}

sandbox.lifecycle.paused

json{
  "version": "v2",
  "id": "6b706076-11b4-5adf-a119-ad785f370045",
  "type": "sandbox.lifecycle.paused",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "pause",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "execution": {
      "execution_time": 60000,
      "memory_mb": 1024,
      "started_at": "2026-11-22T03:03:05Z",
      "vcpu_count": 2
    },
    "pause_mode": "full",
    "sandbox_metadata": {
      "user": "example"
    }
  }
}

sandbox.lifecycle.resumed

json{
  "version": "v2",
  "id": "6054f537-006b-5f84-8001-3792d9c4b390",
  "type": "sandbox.lifecycle.resumed",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "resume",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "7a41c2e8-93b5-4f06-a1d7-2e6c9b0f4d83",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "resume_mode": "restore",
    "sandbox_metadata": {
      "user": "example"
    }
  }
}

sandbox.lifecycle.killed

json{
  "version": "v2",
  "id": "15ec9fd1-ebb0-58f7-8a6c-b72c63f435dd",
  "type": "sandbox.lifecycle.killed",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "kill",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "7a41c2e8-93b5-4f06-a1d7-2e6c9b0f4d83",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "execution": {
      "execution_time": 60000,
      "memory_mb": 1024,
      "started_at": "2026-11-22T03:03:05Z",
      "vcpu_count": 2
    },
    "kill_reason": "request",
    "sandbox_metadata": {
      "user": "example"
    }
  }
}

sandbox.lifecycle.updated

json{
  "version": "v2",
  "id": "41d213e4-7798-5565-9064-0fc0599be5bf",
  "type": "sandbox.lifecycle.updated",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "update",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "sandbox_metadata": {
      "user": "example"
    },
    "set_timeout": "2026-11-22T03:14:05Z"
  }
}

sandbox.lifecycle.checkpointed

json{
  "version": "v2",
  "id": "83dc9783-d088-5a8a-996c-925f639df4a0",
  "type": "sandbox.lifecycle.checkpointed",
  "timestamp": "2026-11-22T03:04:05Z",
  "event_category": "lifecycle",
  "event_label": "checkpoint",
  "sandbox_id": "ixyz1234abcd",
  "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e",
  "sandbox_template_id": "base",
  "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001",
  "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b",
  "events_ttl_days": 30,
  "event_data": {
    "sandbox_metadata": {
      "user": "example"
    }
  }
}

JSON Schema

The body of every sandbox event (JSON Schema 2020-12). Fields may be added; a receiver ignores the ones it does not know.

json{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "version",
    "id",
    "type",
    "timestamp",
    "event_category",
    "event_label",
    "sandbox_id",
    "sandbox_execution_id",
    "sandbox_template_id",
    "sandbox_build_id",
    "sandbox_team_id",
    "events_ttl_days"
  ],
  "properties": {
    "version": {
      "const": "v2",
      "type": "string"
    },
    "id": {
      "description": "the event's id, the same on every attempt",
      "format": "uuid",
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "timestamp": {
      "format": "date-time",
      "type": "string"
    },
    "event_category": {
      "const": "lifecycle",
      "type": "string"
    },
    "event_label": {
      "enum": [
        "create",
        "resume",
        "pause",
        "kill",
        "update",
        "checkpoint"
      ],
      "type": "string"
    },
    "sandbox_id": {
      "type": "string"
    },
    "sandbox_execution_id": {
      "description": "the run: from a start (created, resumed) to its end (paused, killed)",
      "type": "string"
    },
    "sandbox_template_id": {
      "type": "string"
    },
    "sandbox_build_id": {
      "type": "string"
    },
    "sandbox_team_id": {
      "format": "uuid",
      "type": "string"
    },
    "events_ttl_days": {
      "description": "how many days the events API keeps the event",
      "type": "integer"
    },
    "event_data": {
      "properties": {
        "execution": {
          "properties": {
            "execution_time": {
              "description": "milliseconds the run took (paused, killed)",
              "type": "integer"
            },
            "memory_mb": {
              "type": "integer"
            },
            "started_at": {
              "format": "date-time",
              "type": "string"
            },
            "vcpu_count": {
              "type": "integer"
            }
          },
          "type": "object"
        },
        "kill_reason": {
          "description": "killed: why, as the orchestrator tells it (request, timeout, admin, orphaned, unknown, …); orphaned when the cluster lost the end",
          "type": "string"
        },
        "network_egress": {
          "description": "updated: the sandbox's new egress rules",
          "type": "object"
        },
        "pause_mode": {
          "description": "paused: full (memory and file system) or filesystem",
          "type": "string"
        },
        "platformSuspended": {
          "description": "why the platform had stopped the customer when the run ended (a hint)",
          "type": "string"
        },
        "reason": {
          "description": "lost: the cluster has no record of the end",
          "type": "string"
        },
        "resume_mode": {
          "description": "resumed: restore (memory restored) or reboot (booted from the file system)",
          "type": "string"
        },
        "sandbox_metadata": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        "set_timeout": {
          "description": "updated: the sandbox's new end",
          "format": "date-time",
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}

Kill reasons

kill_reasonWhen
requestThe sandbox was killed through the API or the console.
timeoutThe sandbox reached its timeout.
orphanedThe cluster lost the end of the run (its node went away); event_data.reason is lost.
adminThe run ended while the platform had stopped the account (see platformSuspended).
unknownThe reconciliation sent the event and the reason is not in its records.

The cluster can send other values; treat an unknown value as unknown.

Signing secret

  • Each endpoint has a secret (whsec_ followed by base64), made by the platform and shown when the endpoint is created.
  • Reveal shows the secrets that sign now. It asks for a recent sign-in, and each reveal is recorded.
  • Rotate makes a new secret. The previous one keeps signing for the time chosen (now, 24 hours or 7 days), so receivers can switch over: during that time each request carries both signatures.

Address rules

  • https only, port 443 or none, no user information in the address.
  • A domain name, not an IP address in any form.
  • Local names and the platform's own domains are refused.
  • Redirects are not followed.
  • The address is checked again when a request is sent: a name that now leads to a private or internal address is not connected to.

In the console

  • Endpoints: create, edit, pause, disable, delete; send an example of any type; reveal and rotate the secret; health and attempts by hour.
  • Deliveries: every delivery with its attempts' requests and responses (signatures hidden), filtered by endpoint, status and type; Resend.
  • Events: the account's events, with the deliveries of each.

REST API

https://api.lumicloud.ai/v1/webhooks/ does everything the console does. Its OpenAPI description is at https://api.lumicloud.ai/v1/webhooks/openapi.yaml.

  • Authentication: Authorization: Bearer lumi_sk_..., an account API key made on the account page. Scope webhooks:read reads; webhooks also creates, changes, deletes and reveals secrets.
  • Paths: /event-types, /endpoints, /endpoints/{id}, /endpoints/{id}/secret, /endpoints/{id}/secret/rotate, /endpoints/{id}/test, /endpoints/{id}/stats, /deliveries, /deliveries/{id}, /deliveries/{id}/resend, /events.
  • Idempotency-Key on creating an endpoint, rotating a secret and resending: a repeat within 24 hours gets the first answer.
  • Lists are {"data": [...], "next_cursor": ...}; limit is 1 to 100. Errors are {"error": {"code", "message"}}.
  • 20 requests a second per key.
bashcurl https://api.lumicloud.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer $LUMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks", "filters": ["sandbox.lifecycle.*"]}'

Limits and retention

An account can have 10 endpoints, active or not; creating one more is refused (409 endpoint_limit). Events, deliveries and attempts are kept for 30 days, then deleted.

Errors

  • 400 invalid_request, bad_url (an address the rules refuse), unknown_event_type.
  • 401 unauthenticated; 403 forbidden, insufficient_scope.
  • 404 not_found; 409 endpoint_limit, endpoint_disabled.
  • 429 rate_limited, too_often (examples and resends have their own limit).
NextLimits and billing →