> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get webhooks when a sandbox changes state

> Add a webhook endpoint, check the signature of each request, and answer it.

Add a webhook endpoint to your workspace. Your endpoint then gets a signed `POST` request when a sandbox is running, stopped, failed, or deleted. You do not have to read the sandbox again and again.

Write the code that receives sandbox webhooks.

Add a webhook endpoint with POST /v1/webhooks and keep the secret from the response.
In the handler, check the vms-signature header: v1= and the hex HMAC-SHA256 of the event ID, a dot, the vms-timestamp value, a dot, and the raw body, with the secret as the key.
Refuse a timestamp that is more than 5 minutes old.
Answer 2xx within 10 seconds, and ignore an event ID that you already have.
Do not ask me to share my API key or the secret.

## Before you start

* You need an API key with the `webhooks:write` scope. A key with `webhooks:read` can only list and get the endpoints. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* You need an HTTPS URL that the internet can reach. The API refuses `http://` URLs and private addresses, such as `localhost` or `10.0.0.1`.

## Add an endpoint

Send `POST /v1/webhooks` with the `url`. Send `events` to get only some events. The default is each event. See the [list of events](https://vms.dev/docs/reference/webhook-events.md#events).

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/vms-webhooks",
    events: ["sandbox.running", "sandbox.failed"],
  }),
});

const endpoint = await response.json();

console.log(endpoint.id, endpoint.secret);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/webhooks \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/vms-webhooks", "events": ["sandbox.running", "sandbox.failed"]}'
```

The API answers `201` with the endpoint and its `secret`:

```json theme={null}
{
  "id": "whk_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "url": "https://example.com/vms-webhooks",
  "description": null,
  "events": ["sandbox.running", "sandbox.failed"],
  "enabled": true,
  "createdAt": "2026-11-16T02:10:00.000Z",
  "updatedAt": "2026-11-16T02:10:00.000Z",
  "secret": "whsec_0p6gq1x2Yb3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9"
}
```

> [!WARNING]
>
> You see the secret only in this response. Keep it in a secret store. If you lose it, delete the endpoint and add a new one.

A workspace can have 10 endpoints. An 11th endpoint answers `409`.

## Check the signature

Each request has these headers:

| Header | Value |
| - | - |
| `vms-event-id` | The event ID, such as `evt_06d8k3m7q2v9x4b1n5c0e8f2ja` |
| `vms-event-type` | The event type, such as `sandbox.running` |
| `vms-timestamp` | The time of the attempt, in seconds since 1970-01-01 UTC |
| `vms-signature` | `v1=` and the hex HMAC-SHA256 of `<event ID>.<timestamp>.<body>` |

Calculate the signature from the raw body, before you parse the JSON. Use the secret of the endpoint as the key. Compare in constant time, and refuse a timestamp that is more than 5 minutes from your clock.

```typescript TypeScript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

export async function handleWebhook(request: Request) {
  const body = await request.text();
  const eventId = request.headers.get("vms-event-id") ?? "";
  const timestamp = request.headers.get("vms-timestamp") ?? "";
  const signature = request.headers.get("vms-signature") ?? "";

  const expected = `v1=${createHmac("sha256", process.env.VMS_WEBHOOK_SECRET ?? "")
    .update(`${eventId}.${timestamp}.${body}`)
    .digest("hex")}`;

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS;
  const valid =
    expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!fresh || !valid) return new Response(null, { status: 400 });

  const event = JSON.parse(body);

  console.log(event.type, event.data.sandbox.id, event.data.sandbox.state);

  return new Response(null, { status: 204 });
}
```

```bash cURL theme={null}
# Calculate the signature of a saved request body with openssl.
printf '%s' "$EVENT_ID.$TIMESTAMP.$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$VMS_WEBHOOK_SECRET" -hex
```

## Answer the request

Answer with a `2xx` status within 10 seconds. Do long work after you answer.

If the endpoint answers with a different status, answers too late, or cannot be reached, the request comes again. Each event has up to 8 attempts. See the [retry times](https://vms.dev/docs/reference/webhook-events.md#retries).

An event can come more than one time. Each attempt has the same event ID. Keep the IDs that you processed, and ignore an ID that you already have. Events can come in a different sequence from the changes. Use `createdAt` of the event to find the latest change.

## Change or delete an endpoint

* Send `PATCH /v1/webhooks/{id}` with the fields to change. Send `"enabled": false` to stop the events and keep the endpoint.
* Send `DELETE /v1/webhooks/{id}` to delete the endpoint. Attempts that wait for a retry stop.
* Send `GET /v1/webhooks` to list the endpoints. The list does not show the secrets.
* Send `POST /v1/webhooks/update-many` with `items`, or `POST /v1/webhooks/delete-many` with `ids`, to change or delete up to 500 endpoints in one request. The answer has a result for each item. There is no create of many endpoints, because the API shows the secret of an endpoint only in the answer of its create.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.