> ## 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.

# Webhook events

> The events, the request body, the headers, and the retry times of webhooks.

To add an endpoint and check the signature, see [Get webhooks when a sandbox changes state](https://vms.dev/docs/sandboxes/webhooks.md).

## Events

| Event | When |
| - | - |
| `sandbox.running` | The sandbox is `running`. |
| `sandbox.stopped` | The sandbox is `stopped`. |
| `sandbox.error` | The sandbox is in the `error` state. |
| `sandbox.degraded` | The sandbox is `running`, but its health is `degraded`. With `data.reason` set to `hydration_failed`, the download of its saved files stopped for good. |
| `sandbox.recovered` | The health of the sandbox is `ok` again. |
| `sandbox.deleted` | The sandbox and its data are removed. |
| `sandbox.failed` | The sandbox did not start, for example because no host had room. |
| `sandbox.hydrated` | Each saved file is on the local disk after a resume, a fork, a start from a template, or a recovery after a host failure. It goes out one time for each restore. See [Hydration](https://vms.dev/docs/sandboxes/stop-and-resume.md#hydration). |

See [Health and recovery](https://vms.dev/docs/reference/health-and-recovery.md) for when a sandbox is `degraded`, and when a host failure moves it to `error`.

## Request

Each event is a `POST` request with a JSON body:

```json theme={null}
{
  "id": "evt_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "type": "sandbox.running",
  "createdAt": "2026-11-16T02:10:01.000Z",
  "data": {
    "sandbox": {
      "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
      "name": null,
      "state": "running",
      "size": "small",
      "health": "ok",
      "errorReason": null,
      "labels": {}
    }
  }
}
```

| Field | Value |
| - | - |
| `id` | The event ID. Each attempt of an event has the same ID. |
| `type` | One of the [events](#events). |
| `createdAt` | The time of the change. |
| `data.sandbox` | The sandbox at the time of the change. To get all fields, send [`GET /v1/sandboxes/{id}`](https://vms.dev/docs/api-reference/sandboxes/get-a-sandbox). |
| `data.reason` | Only in some events: `hydration_failed` in a `sandbox.degraded` event when the download of the saved files stopped for good. |

## Headers

| Header | Value |
| - | - |
| `content-type` | `application/json` |
| `user-agent` | `vms-webhooks/1` |
| `vms-event-id` | The event ID |
| `vms-event-type` | The event type |
| `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>`, with the secret of the endpoint as the key |

Each attempt has a new timestamp and a new signature.

## Retries

An attempt succeeds when your endpoint answers with a `2xx` status within 10 seconds. A redirect is a failure. After a failure, the next attempt comes after this time:

| After attempt | Next attempt |
| - | - |
| 1 | 30 seconds |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 30 minutes |
| 5 | 1 hour |
| 6 | 3 hours |
| 7 | 6 hours |
| 8 | No more attempts |

So each event has up to 8 attempts in about 11 hours.

## Limits

| Limit | Value |
| - | - |
| Endpoints in a workspace | 10 |
| URL | HTTPS, with a public host name, 2,048 characters or fewer |
| Description | 200 characters or fewer |
| Time to answer | 10 seconds |

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


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