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

# Webhooks

> 在训练或评估运行结束时接收 HTTP POST 通知

Webhooks 会在运行结束时通知您的系统。Osmosis 会向您配置的 URL 发送带有 JSON payload 的 `POST` 请求，每个完成的运行发送一次。

## 设置

打开 **Workspace Settings → Webhooks**（仅限 owner 和 admin）：

1. 输入您的 **Webhook URL**。必须使用 HTTPS 且端口为 443，并且解析到公网地址。指向私有或内部网络的 URL 会被拒绝。
2. 打开 **Deliver events** 并点击 **Save**。
3. 点击 **Send test payload**，确认您的接收端收到 `webhook.test` 事件。

关闭 **Deliver events** 可以暂停投递，且不会丢失已保存的 URL。如需彻底移除 webhook，请清空 **Webhook URL** 并点击 **Save**。

## 事件

| 事件                       | 发送时机                       |
| ------------------------ | -------------------------- |
| `training_run.completed` | 训练运行结束时                    |
| `eval_run.completed`     | 评估运行结束时                    |
| `webhook.test`           | 点击 **Send test payload** 时 |

## Payload

每个请求都是 `Content-Type: application/json` 的 `POST`，采用以下结构：

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
{
  "event": "training_run.completed",
  "timestamp": "2026-07-15T22:14:05.123456+00:00",
  "data": {}
}
```

### `training_run.completed` 和 `eval_run.completed`

两种事件的 `data` 对象结构相同：

| 字段                 | 说明                                                                              |
| ------------------ | ------------------------------------------------------------------------------- |
| `id`               | 运行 ID                                                                           |
| `name`             | 运行名称                                                                            |
| `status`           | 运行的最终状态：`finished`、`failed` 或 `stopped`                                         |
| `started_at`       | 运行开始时间，ISO 8601 格式                                                              |
| `completed_at`     | 运行结束时间，ISO 8601 格式                                                              |
| `duration_seconds` | 运行总时长（秒）                                                                        |
| `model_name`       | 运行使用的模型名称                                                                       |
| `dataset`          | 数据集的 `{ "id", "name" }`，或 `null`                                                |
| `rollout`          | rollout 的 `{ "id", "name" }`，或 `null`                                           |
| `platform_url`     | 平台中运行详情页的链接                                                                     |
| `latest_metrics`   | 训练运行：每个运行指标的最新记录值，按指标名称组织。评估运行：运行的最终汇总结果，包含 reward distribution（`reward_stats`） |

训练运行示例：

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
{
  "event": "training_run.completed",
  "timestamp": "2026-07-15T22:14:05.123456+00:00",
  "data": {
    "id": "a1b2c3d4-0000-0000-0000-000000000000",
    "name": "my-training-run",
    "status": "finished",
    "started_at": "2026-07-15T20:01:12+00:00",
    "completed_at": "2026-07-15T22:14:03+00:00",
    "duration_seconds": 7971,
    "model_name": "Qwen3-8B",
    "dataset": { "id": "d1e2f3a4-0000-0000-0000-000000000000", "name": "my-dataset" },
    "rollout": { "id": "r1s2t3u4-0000-0000-0000-000000000000", "name": "my-rollout" },
    "platform_url": "https://platform.osmosis.ai/my-workspace/training/a1b2c3d4-0000-0000-0000-000000000000",
    "latest_metrics": {
      "rollout/raw_reward": 0.82,
      "eval/validation/reward": 0.79,
      "train/entropy_loss": 1.24,
      "rollout/response_lengths": 512,
      "rollout/total_lengths": 1930,
      "rollout/truncated_ratio": 0.03
    }
  }
}
```

评估运行的 `latest_metrics` 则包含最终汇总结果：

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
"latest_metrics": {
  "total_runs": 200,
  "graded": 198,
  "passed": 154,
  "failed": 44,
  "skipped": 2,
  "pass_rate": 0.78,
  "pass_threshold": 0.5,
  "score": 0.71,
  "reward_stats": {
    "mean": 0.71,
    "median": 0.74,
    "std": 0.18,
    "min": 0.05,
    "max": 0.98,
    "pass_at_k": { "1": 0.78, "4": 0.91 }
  },
  "total_tokens": 1834520,
  "total_duration_ms": 5421000
}
```

### `webhook.test`

| 字段          | 说明           |
| ----------- | ------------ |
| `workspace` | Workspace 名称 |
| `message`   | 确认消息         |

## 投递

* 每次尝试的超时时间为 5 秒。投递失败最多重试 2 次，并采用退避策略。
* 任何 2xx 响应都视为投递成功。不会跟随重定向。
* 投递为尽力而为：webhook 失败不会影响运行本身。