Webhooks

{
  "type": "sandbox.stopped",
  "sandboxId": "sb-3f9a…",
  "eventId": "sb-3f9a…:3:142",
  "event": {
    "id": "sb-3f9a…:3:142", "ts": "2026-06-24T12:00:00Z",
    "orgId": "…", "sandboxId": "sb-3f9a…",
    "type": "sandbox.stopped", "data": { "reason": "user_requested" }
  }
}

​

Events

​

Destinations

import { Webhooks } from "@opencomputer/sdk";

const webhooks = new Webhooks({ apiKey: process.env.OPENCOMPUTER_API_KEY! });

const { id, secret } = await webhooks.create({
  url: "https://app.example.com/oc-webhook",
  eventTypes: ["sandbox.stopped", "sandbox.ready"],
  name: "prod",            // optional display name
});
// `secret` (whsec_…) verifies deliveries — returned here and re-fetchable via webhooks.getSecret(id).

​

Subscribe at create

import { Sandbox } from "@opencomputer/sdk";

const sandbox = await Sandbox.create({
  webhooks: [{ url: "https://app.example.com/oc-webhook" }],
});
// the generated signing secret is on the create response: sandbox.webhooks[0].secret

​

Deliveries

Delivery = { id, status: "success" | "pending" | "failed", responseStatusCode?, timestamp }

​

Signing, retries, and dedupe

• HTTPS only, checked at registration. The delivery layer (Svix) additionally blocks private, loopback, link-local, and cloud-metadata addresses at send time.
• Always signed with Standard Webhooks (delivery is by Svix). Every request carries svix-id, svix-timestamp, and svix-signature = v1,<base64(HMAC-SHA256(secret, "{svix-id}.{svix-timestamp}.{rawBody}"))>. Verify against the raw request body, before parsing it; the timestamp guards replay. Any custom headers you attached as destination metadata ride along too. Your signing secret is re-fetchable any time via GET /api/webhooks/{id}/secret and rotatable via update (rotateSecret: true).
• At-least-once. Once an event is handed off it’s retried until it succeeds or the delivery layer gives up. A duplicate can still arrive, so dedupe on svix-id (the verifier exposes it as both deliveryId and dedupeId).
• Not strictly ordered. Events for one sandbox can arrive out of order (e.g. sandbox.ready before sandbox.created). Treat each event independently and key off event.type; don’t assume an ordering.
• Success / retry / give-up. A delivery succeeds on HTTP 2xx. Failures are retried on Svix’s managed backoff (immediately, then 5s, 5m, 30m, 2h, 5h, 10h, 10h); an endpoint that keeps failing for ~5 days is auto-disabled. Inspect attempts and recover failed messages via the deliveries API. Unsafe targets (private / loopback / cloud-metadata addresses) are blocked by the delivery layer.

​

Verify a webhook

import { verifyWebhook, type SandboxLifecycleEvent } from "@opencomputer/sdk";

// rawBody = the RAW request body string, read BEFORE JSON.parse.
// Throws on a missing / expired / invalid signature.
const delivery = await verifyWebhook<SandboxLifecycleEvent>(rawBody, request.headers, process.env.OC_WEBHOOK_SECRET!);

if (delivery.type === "sandbox.stopped") {
  console.log(delivery.sandboxId, delivery.event.data.reason); // event.data is typed per event
}