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
| Event | When |
|---|---|
| sandbox.lifecycle.created | A sandbox was created and started. |
| sandbox.lifecycle.paused | A sandbox was paused: its run ended and it can be resumed (event_data.pause_mode: full, or filesystem). |
| sandbox.lifecycle.resumed | A paused sandbox was resumed (event_data.resume_mode: restore, or reboot from its file system). |
| sandbox.lifecycle.killed | A sandbox was killed, timed out or lost: its run ended and it is gone (event_data.kill_reason says why). |
| sandbox.lifecycle.updated | A running sandbox's timeout or network was changed (event_data.set_timeout, network_egress); several in a run. |
| sandbox.lifecycle.checkpointed | A 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
| Header | Value |
|---|---|
| content-type | application/json |
| user-agent | LumiCloud-Webhooks/1 |
| webhook-id | The event's ID, the same for every attempt and resend. |
| webhook-timestamp | When the request was signed, in Unix seconds. |
| webhook-signature | v1,<signature>, one for each secret that signs now, separated by spaces. |
| lumi-delivery-id | The delivery (this event to this endpoint). |
| lumi-attempt | The attempt's number, from 1. |
| lumi-test | true 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"
}
}| Field | Meaning |
|---|---|
| id | The event's ID (also webhook-id). |
| type, event_category, event_label | The event type; lifecycle; create, pause, resume, kill, update or checkpoint. |
| timestamp | When the event happened (UTC, RFC 3339). |
| sandbox_id, sandbox_execution_id | The sandbox, and the run it was in (a resume starts a new run). |
| sandbox_template_id, sandbox_build_id, sandbox_team_id | The template and build the sandbox started from, and your account's team ID. |
| events_ttl_days | How many days the event is kept and available from the events API. |
| event_data.sandbox_metadata | The metadata given when the sandbox was created, as given. |
| event_data.execution | On paused and killed events: started_at, vcpu_count, memory_mb of the run, and execution_time in milliseconds. |
| event_data.kill_reason | On killed events, see below. |
| event_data.pause_mode, resume_mode | On paused and resumed events: how the sandbox was paused or resumed. |
| event_data.set_timeout, network_egress | On updated events: the new timeout or network settings. |
| event_data.platformSuspended | On 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_reason | When |
|---|---|
| request | The sandbox was killed through the API or the console. |
| timeout | The sandbox reached its timeout. |
| orphaned | The cluster lost the end of the run (its node went away); event_data.reason is lost. |
| admin | The run ended while the platform had stopped the account (see platformSuspended). |
| unknown | The 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).