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

> ## Agent Instructions
> Install the Beam CLI, sign in, and connect coding agents to the Beam MCP server with `curl -fsSL https://www.beam.cloud/install | sh`. To also create a VM, run `curl -fsSL https://www.beam.cloud/install | sh -s -- --vm`.
> VMs are persistent Linux machines without GPUs. Defaults: 4 CPUs, 8 GiB of RAM, a 50 GiB disk, Ubuntu 24.04, and a browser desktop. A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep.
> Stopping a VM keeps its disk and discards RAM and processes. Pausing keeps both, and resuming restores them. To pause after 5 idle minutes and wake on access, run `beam vm update NAME --ttl 300 --idle-action pause --auto-resume`.
> Core VM commands: `beam vm new NAME`, `beam vm ssh NAME`, `beam vm sync NAME ./dir`, `beam vm exec NAME -- CMD`, `beam vm expose NAME PORT --protected`, `beam vm fork NAME NEW_NAME`, `beam vm pause NAME`, `beam vm stop NAME`, `beam vm rm NAME`.
> For GPUs, use a sandbox or a deployed endpoint. Sandboxes are disposable environments that boot in seconds and fork from snapshots.
> Current rates are at https://www.beam.cloud/pricing.

# Webhooks

> Receive signed events from your workspace

Webhooks send deployment and task events to your service. Create one in **Settings → Webhooks**, through MCP's `create_webhook`, or with the API below. For task results, use [callbacks](https://docs.beam.cloud/v2/topics/callbacks.md).

## Subscribe

With `BEAM_TOKEN` and `WORKSPACE_ID` set in your environment:

```bash theme={null}
curl --fail-with-body -X POST \
  "https://app.beam.cloud/api/v1/webhook/$WORKSPACE_ID" \
  -H "Authorization: Bearer $BEAM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-service.example/beam-events","event_types":["task.*","stub.deploy"],"description":"Deployment and task events"}'
```

Save the signing secret from the response. It is only shown once.

Filter by event name, such as `stub.deploy`, or prefix, such as `task.*`. Use `*` or an empty list for all eligible events.

Logs, container metrics, and internal platform events are excluded. Use [logs and metrics](https://docs.beam.cloud/v2/operations/observability.md) for those.

## Verify Signatures

Requests use CloudEvents JSON with `Content-Type: application/cloudevents+json`. Headers include:

| Header | Meaning |
| - | - |
| `X-Beta9-Signature` | `sha256=` followed by a hex HMAC-SHA256 of the raw request body |
| `X-Beta9-Event` | Event type |
| `X-Beta9-Delivery` | Event ID |

Verify the raw body using the full signing secret, including `whsec_`:

```python theme={null}
import hashlib
import hmac


def valid_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

> [!NOTE]
>
> Delivery times out after 10 seconds and is not retried. Handle duplicate event IDs and use the workspace API to recover missed updates.

## Manage Subscriptions

| Method | Path (under `/api/v1`) | Action |
| - | - | - |
| GET | `/webhook/{workspaceId}` | List subscriptions |
| POST | `/webhook/{workspaceId}` | Create a subscription |
| PATCH | `/webhook/{workspaceId}/{webhookId}` | Update URL, filters, description, or enabled state |
| DELETE | `/webhook/{workspaceId}/{webhookId}` | Delete a subscription |
| POST | `/webhook/{workspaceId}/{webhookId}/test` | Send a test event |

Changes can take about 15 seconds to apply.


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