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

# 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](/v2/topics/callbacks).

## 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](/v2/operations/observability) 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.
</Note>

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