---
title: Webhook Alerts
description: Receive alert notifications as HTTP POST requests to an endpoint you control.
---

# Webhook alerts

Webhook alerts deliver alert notifications to an endpoint you configure. Each time an alert is triggered or resolved, an HTTP POST request is sent to your endpoint with a structured JSON payload.

The payload format is consistent across all alert events. Field values shown in this document are sample data to help you understand the structure and integrate your system.

---

### HTTP method

All webhook requests use the POST method.

### Request headers

| Header | Value | Description |
|---|---|---|
| `Content-Type` | `application/json` | Sent with every request. |
| `Authorization` | `Bearer <token>` | Optional. Include if your endpoint requires authentication. |
| Custom headers | — | Optional. Configurable per endpoint. A maximum of 5 custom key-value header pairs can be added. |


---

### Request payload

The following is a representative webhook payload. Your endpoint will receive this structure on every alert event.

```json
{
  "version": "v1",
  "monitoring_group_id": 0,
  "status": "firing",
  "alert": {
    "id": 0,
    "name": "Sample Alert",
    "resource_type": "notebook",
    "metric_type": "cpu",
    "operator": ">",
    "threshold_value": 80,
    "severity": "Warning"
  },
  "project": {
    "id": 0,
    "name": "Sample Project",
    "location": "sample-location"
  },
  "affected_resources": [
    {
      "id": 0,
      "name": "sample-resource",
      "replica": "sample-replica",
      "gpu_uuid": "GPU-SAMPLE"
    }
  ]
}
```

---

### Payload fields

#### Top-level fields

| Field | Type | Description |
|---|---|---|
| `version` | string | Payload schema version. Current value is `v1`. |
| `monitoring_group_id` | integer | Identifier of the monitoring group that owns this alert. |
| `status` | string | Current state of the alert. Possible values: `firing`, `resolved`. |

#### `alert` object

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique identifier for the alert. |
| `name` | string | Display name of the alert. |
| `resource_type` | string | Type of resource being monitored (e.g. `notebook`). |
| `metric_type` | string | Metric being evaluated (e.g. `cpu`). |
| `operator` | string | Comparison operator used in the alert condition (e.g. `>`, `<`, `=`). |
| `threshold_value` | number | The threshold value that triggers the alert when crossed. |
| `severity` | string | Alert severity level. Possible values: `Warning`, `Critical`. |

#### `project` object

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique identifier for the project. |
| `name` | string | Display name of the project. |
| `location` | string | Region or location associated with the project. |

#### `affected_resources` array

Each object in this array represents a resource impacted by the alert.

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique identifier for the resource. |
| `name` | string | Display name of the resource. |
| `replica` | string | Replica identifier associated with the resource. |
| `gpu_uuid` | string | UUID of the GPU assigned to the resource, if applicable. |

---

### Endpoint requirements

Your endpoint must meet the following requirements to receive and process webhook notifications correctly.

- Accept incoming POST requests with a `Content-Type` of `application/json`.
- Return a `2xx` HTTP status code to acknowledge successful receipt. Any other response code is treated as a delivery failure.
- If your endpoint uses token-based authentication, validate the `Authorization` header before processing the request body.

> **Note:** If your endpoint does not return a `2xx` response, the webhook delivery will be considered failed. Ensure your endpoint handles the request and responds promptly to avoid missed notifications.



---