How to receive webhooks for sandbox events

On Runtime, you learn about a sandbox that stopped, failed to start, or could not wake immediately, as it happens. You do not need to run a polling loop. Thirteen event types cover sandboxes, snapshots and volumes. Runtime signs every delivery with HMAC-SHA256. If your endpoint is down, Runtime retries ten times over about three days. Each delivery is logged with your endpoint's status and timing. Webhooks cost nothing extra (metrics and webhooks).

Create a webhook

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const hook = await runtime.webhooks.create({  url: "https://example.com/hooks/runtime",  events: ["sandbox.stopped", "sandbox.start_failed", "sandbox.wake_failed"],});console.log(hook.id, hook.secret); // the secret is shown once: store it nowconst answer = await runtime.webhooks.test(hook.id); // a signed webhook.test, sent nowconsole.log(answer.lastStatus);

Pythonfrom withruntime import Runtimeruntime = Runtime()hook = runtime.webhooks.create(    url="https://example.com/hooks/runtime",    events=["sandbox.stopped", "sandbox.start_failed", "sandbox.wake_failed"],)print(hook["id"], hook["secret"])  # shown onceprint(runtime.webhooks.test(hook["id"]))

Terminalnpx withruntime webhooks create https://example.com/hooks/runtime --events sandbox.stopped,sandbox.start_failednpx withruntime webhooks test <id>

If you leave out events, you receive every type. A webhook belongs to the account. Every key and every owner sees the same webhooks. Owners can manage them on the Webhooks page. An account can have 16.

The events

Each body is the event, with the resource as it was at the time of the event. It has the id, type and createdAt fields, and data.sandbox (or data.snapshot, data.volume). That object includes the state, previous state, labels, size, region and funding. Labels you set when you create a resource come back here. A handler can use them to route an event to the job that owns the sandbox.

Write the endpoint

Check the signature, act on the event, and return 204 quickly. Put heavy work in a queue, and do it after the response:

TypeScriptimport { verifyWebhook } from "withruntime";const seen = new Set<string>(); // use your database in productionexport async function POST(request: Request) {  let event;  try {    event = await verifyWebhook(      await request.text(),      request.headers.get("runtime-signature"),      process.env.RUNTIME_WEBHOOK_SECRET!,    );  } catch {    return new Response("bad signature", { status: 400 });  }  const id = request.headers.get("runtime-webhook-id") ?? event.id;  if (seen.has(id)) return new Response(null, { status: 204 }); // a retry of one already handled  seen.add(id);  if (event.type === "sandbox.stopped") {    const sandbox = event.data.sandbox as { id: string; stopReason?: string };    console.log("stopped", sandbox.id, sandbox.stopReason);  }  return new Response(null, { status: 204 });}

For how the signature check works, and how to check it without the SDK, see verify a webhook signature.

Answers, retries and the log

Terminalnpx withruntime webhooks deliveries <id>npx withruntime webhooks retry <deliveryId>npx withruntime webhooks update <id> --disable

The same actions are available in code: runtime.webhooks.deliveries(id) and runtime.webhooks.retry(deliveryId). While deliveries fail, the webhook shows failingSince. An agent manages webhooks with the runtime_webhooks_manage MCP tool.

Mistakes and how Runtime handles them

• Parsing JSON before checking the signature. The signature covers the raw body. Read the body as text first, verify the signature, then use the data.
• Doing slow work before responding. A response after 10 seconds counts as a failure, and Runtime sends the event again. Respond first, then do the work.
• Handling a retry twice. A retry carries the same Runtime-Webhook-Id; skip one you have already handled.
• An endpoint on a private address. A URL with a private address is refused when you create the webhook. Each delivery resolves the name again and connects only to the public address it checked.
• Missing events while the endpoint was down. Nothing is lost for 14 days. runtime events (or runtime.events.list()) lists every lifecycle event, newest first, for the account or for one sandbox.

Related

• Read sandbox metrics for CPU and memory over time.
• Pause and resume a sandbox, whose sandbox.paused and sandbox.woken events are sent here.
• OpenTelemetry export sends the same events to Grafana, Datadog or Honeycomb as logs.

Start

Terminalnpx withruntime webhooks create https://example.com/hooks/runtime

The first command prints a link to approve in your browser. New accounts get 100 free hours of a 1 GB machine in its first 30 days, with no card.

Facts on this page were checked on 26 October 2026.