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

# Webhook Event Reference

> Event names, delivery envelope, payload fields, lifecycle semantics, and examples for Tensorlake webhooks.

Every Tensorlake lifecycle webhook is a versioned JSON object. The common
envelope identifies the event, project, producer ordering domain, and
event-specific data.

## Common envelope

| Field             | Type    | Description                                                                            |
| ----------------- | ------- | -------------------------------------------------------------------------------------- |
| `event_id`        | string  | Stable event identifier beginning with `evt_`. Use it as the deduplication key.        |
| `event_type`      | string  | One supported lifecycle event name.                                                    |
| `event_version`   | integer | Payload schema version. The current version is `1`.                                    |
| `occurred_at`     | string  | RFC 3339 UTC time when the lifecycle transition was recorded.                          |
| `project_id`      | string  | Public ID of the project that produced the event.                                      |
| `source_id`       | string  | Opaque identifier for the producer ordering domain.                                    |
| `source_revision` | string  | Unsigned decimal source revision. Keep it as a string to avoid integer precision loss. |
| `source_ordinal`  | integer | Zero-based order when one source revision produces multiple events.                    |
| `data`            | object  | Event-specific sandbox, application, or request data.                                  |

`event_id` remains the same across retries. Delivery order is not guaranteed.
For related events from the same `source_id`, compare `source_revision`
numerically and then `source_ordinal` when you need source order.

## Event catalog

### Sandbox events

| Event type                      | Emitted when                                                                           |
| ------------------------------- | -------------------------------------------------------------------------------------- |
| `tensorlake.sandbox.created`    | A sandbox is persisted for the first time.                                             |
| `tensorlake.sandbox.running`    | A sandbox enters the running state.                                                    |
| `tensorlake.sandbox.suspended`  | A sandbox enters the suspended state.                                                  |
| `tensorlake.sandbox.resumed`    | A suspended sandbox begins a new generation. Its public status is initially `pending`. |
| `tensorlake.sandbox.terminated` | A sandbox terminates without a failure outcome.                                        |
| `tensorlake.sandbox.failed`     | A sandbox terminates with a failure outcome.                                           |

Sandbox event `data` contains `previous_status` and a `sandbox` object.

| Sandbox field    | Type           | Description                                                       |
| ---------------- | -------------- | ----------------------------------------------------------------- |
| `id`             | string         | Sandbox ID.                                                       |
| `name`           | string or null | Name of a named sandbox, when present.                            |
| `type`           | string         | `named` or `ephemeral`.                                           |
| `image`          | string or null | Sandbox image, when present.                                      |
| `generation_id`  | integer        | Sandbox generation, starting at `1` and increasing on resume.     |
| `status`         | string         | `pending`, `running`, `suspended`, or `terminated`.               |
| `outcome`        | string or null | `success`, `failure`, or `null` while no terminal outcome exists. |
| `outcome_reason` | string or null | Allowlisted terminal reason, when available.                      |
| `snapshot_id`    | string or null | Snapshot associated with the sandbox, when present.               |
| `created_at`     | string         | RFC 3339 sandbox creation time.                                   |
| `resources`      | object         | Requested CPU, memory, disk, and GPU resources.                   |

```json Sandbox failed event theme={null}
{
  "event_id": "evt_019f95fb-7f33-7000-8000-000000000006",
  "event_type": "tensorlake.sandbox.failed",
  "event_version": 1,
  "occurred_at": "2026-07-24T21:15:15.123Z",
  "project_id": "project_123",
  "source_id": "src_01k0example",
  "source_revision": "81247",
  "source_ordinal": 0,
  "data": {
    "previous_status": "running",
    "sandbox": {
      "id": "9q2j1f4n6y8x0r3k5m7pa",
      "name": "build-runner",
      "type": "named",
      "image": "tensorlake/default",
      "generation_id": 2,
      "status": "terminated",
      "outcome": "failure",
      "outcome_reason": "out_of_memory",
      "snapshot_id": null,
      "created_at": "2026-07-24T20:10:00Z",
      "resources": {
        "cpus": 2,
        "memory_mb": 4096,
        "disk_mb": 20480,
        "gpu_count": 0,
        "gpu_model": null
      }
    }
  }
}
```

Possible sandbox failure reasons are `unknown`, `user_terminated`, `timeout`,
`internal_error`, `constraint_unsatisfiable`, `executor_removed`,
`out_of_memory`, `container_startup_failed`, `pool_deleted`,
`container_terminated`, `bad_image`, `image_not_found`,
`container_unhealthy`, `function_error`, `function_timeout`,
`function_cancelled`, `desired_state_removed`, `process_crash`, and
`executor_drained`. A successful termination can report `unknown`,
`user_terminated`, or `timeout`. `outcome_reason` can be `null` when no safe
reason is available.

### Application events

| Event type                       | Emitted when                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `tensorlake.application.created` | An application is persisted for the first time.                               |
| `tensorlake.application.updated` | A deployment, metadata, capability, or application state change is persisted. |
| `tensorlake.application.deleted` | An existing application is deleted.                                           |

Application event `data` contains `previous_version`, `previous_state`, and an
`application` object. The previous fields are `null` for a creation event.

| Application field | Type           | Description                                       |
| ----------------- | -------------- | ------------------------------------------------- |
| `name`            | string         | Application name.                                 |
| `version`         | string         | Application version.                              |
| `state`           | string         | `active` or `disabled`.                           |
| `disabled_reason` | string or null | Reason the application is disabled, when present. |
| `created_at`      | string         | RFC 3339 application creation time.               |

```json Application updated event theme={null}
{
  "event_id": "evt_019f95fb-8703-7000-8000-000000000008",
  "event_type": "tensorlake.application.updated",
  "event_version": 1,
  "occurred_at": "2026-07-24T21:15:17.123Z",
  "project_id": "project_123",
  "source_id": "src_01k0example",
  "source_revision": "81249",
  "source_ordinal": 0,
  "data": {
    "previous_version": "2026-07-23",
    "previous_state": "active",
    "application": {
      "name": "invoice-parser",
      "version": "2026-07-24",
      "state": "active",
      "disabled_reason": null,
      "created_at": "2026-04-11T18:12:00Z"
    }
  }
}
```

### Application-request events

| Event type                                 | Emitted when                                            |
| ------------------------------------------ | ------------------------------------------------------- |
| `tensorlake.application.request.created`   | An application request is created.                      |
| `tensorlake.application.request.completed` | An application request completes successfully.          |
| `tensorlake.application.request.failed`    | An application request reaches a failed terminal state. |

Application-request event `data` contains an `application` identity and a
`request` object.

| Request field    | Type           | Description                                                |
| ---------------- | -------------- | ---------------------------------------------------------- |
| `id`             | string         | Application request ID.                                    |
| `status`         | string         | `created`, `completed`, or `failed`.                       |
| `failure_reason` | string or null | Allowlisted reason for a failed request.                   |
| `created_at`     | string         | RFC 3339 request creation time.                            |
| `finished_at`    | string or null | RFC 3339 terminal time; `null` until the request finishes. |

```json Application request completed event theme={null}
{
  "event_id": "evt_019f9604-13d0-7000-8000-00000000000b",
  "event_type": "tensorlake.application.request.completed",
  "event_version": 1,
  "occurred_at": "2026-07-24T21:24:37.456Z",
  "project_id": "project_123",
  "source_id": "src_01k0example",
  "source_revision": "81252",
  "source_ordinal": 0,
  "data": {
    "application": {
      "name": "invoice-parser",
      "version": "2026-07-24"
    },
    "request": {
      "id": "req_01k0example",
      "status": "completed",
      "failure_reason": null,
      "created_at": "2026-07-24T21:24:35.101Z",
      "finished_at": "2026-07-24T21:24:37.456Z"
    }
  }
}
```

Possible application-request failure reasons are `unknown`, `internal_error`,
`function_error`, `function_timeout`, `request_error`,
`constraint_unsatisfiable`, `cancelled`, and `out_of_memory`.