# Zenfeed Webhook 通知对接指南

Zenfeed 支持通过 Webhook 将分组和总结后的 Feed 通知推送到您指定的 HTTP(S) 端点。这允许您将 Zenfeed 的通知集成到自定义的应用或工作流程中。

## 1. 配置方法

要在 Zenfeed 中配置 Webhook 通知，您需要在配置文件的 `notify.receivers` 部分定义一个或多个接收者，并为每个 Webhook 接收者指定其唯一的 `name` 和 `webhook` 配置块。

**示例配置 (`config.yaml`):**

```yaml
notify:
  # ... 其他通知配置 ...

  receivers:
    - name: my_awesome_webhook # 接收者的唯一名称，将在路由规则中引用
      webhook:
        url: "https://your-service.com/webhook-endpoint" # 您的 Webhook 接收端点 URL

  # 示例：路由规则中如何使用此接收者
  route: # or sub_routes..
    receivers:
      - my_awesome_webhook # 引用上面定义的接收者名称
    # ... 其他路由配置 ...
```

在上述示例中：
- 我们定义了一个名为 `my_awesome_webhook` 的接收者。
- `webhook.url` 字段指定了当有匹配此接收者的通知时，Zenfeed 将向哪个 URL 发送 POST 请求。

## 2. 数据格式详解

当 Zenfeed 向您的 Webhook 端点发送通知时，它会发送一个 `POST` 请求，请求体为 JSON 格式。

请求体结构如下：

```json
{
  "group": "string",
  "labels": {
    "label_key1": "label_value1",
    "label_key2": "label_value2"
  },
  "summary": "string",
  "feeds": [
    {
      "labels": {
        "title": "Feed Title 1",
        "link": "http://example.com/feed1",
        "content": "Feed content snippet 1...",
        "source": "example_source",
        "pub_time": "2024-07-30T10:00:00Z"
        // ... 其他自定义或标准标签
      },
      "time": "2024-07-30T10:00:00Z",
      "related": [
        // 可选：与此 Feed 相关的其他 Feed 对象，结构同父 Feed
      ]
    }
    // ...更多 Feed 对象
  ]
}
```

**字段说明:**

-   `group` (`string`):
    当前通知所属的组名。这个名称是根据通知路由配置中 `group_by` 定义的标签值组合而成的。例如，如果 `group_by: ["source", "category"]`，且一个 Feed 组的 `source` 是 `github_trending`，`category` 是 `golang`，那么 `group` 可能类似于 `"github_trending/golang"`。

-   `labels` (`object`):
    一个键值对对象，表示当前通知组的标签。这些标签是根据通知路由配置中 `group_by` 所指定的标签及其对应的值。
    例如，如果 `group_by: ["source"]` 且当前组的 `source` 标签值为 `rsshub`，则 `labels` 会是 `{"source": "rsshub"}`。

-   `summary` (`string`):
    由大语言模型 (LLM) 为当前这一组 Feed 生成的摘要文本。如果通知路由中没有配置 LLM 总结，此字段可能为空字符串或省略 (取决于具体的实现细节，但通常会是空字符串)。

-   `feeds` (`array` of `object`):
    一个数组，包含了属于当前通知组的所有 Feed 对象。每个 Feed 对象包含以下字段：
    *   `labels` (`object`): Feed 的元数据。这是一个键值对对象，包含了该 Feed 的所有标签，例如：
        *   `title` (`string`): Feed 的标题。
        *   `link` (`string`): Feed 的原始链接。
        *   `content` (`string`): Feed 的内容摘要或全文 (取决于抓取和重写规则)。
        *   `source` (`string`): Feed 的来源标识。
        *   `pub_time` (`string`): Feed 的发布时间 (RFC3339 格式的字符串，例如 `2025-01-01T00:00:00Z`)。
        *   ...以及其他在抓取或重写过程中添加的自定义标签。
    *   `time` (`string`): Feed 的时间戳，通常是其发布时间，采用 RFC3339 格式 (例如 `2025-01-01T00:00:00Z`)。此字段与 `labels.pub_time` 通常一致，但 `time` 是系统内部用于时间序列处理的主要时间字段。
    *   `related` (`array` of `object`, 可选):
        一个数组，包含了与当前 Feed 语义相关的其他 Feed 对象。这通常在通知路由中启用了 `compress_by_related_threshold` 选项时填充。每个相关的 Feed 对象结构与父 Feed 对象完全相同。如果未启用相关性压缩或没有相关的 Feed，此字段可能为空数组或不存在。

## 3. 请求示例

以下是一个发送到您的 Webhook 端点的 JSON 请求体示例：

```json
{
  "group": "my_favorite_blogs",
  "labels": {
    "category": "tech_updates",
  },
  "summary": "今天有多篇关于最新 AI 技术进展的文章，重点关注了大型语言模型在代码生成方面的应用，以及其对未来软件开发模式的潜在影响。",
  "feeds": [
    {
      "labels": {
        "content": "AlphaCode X 展示了惊人的代码理解和生成能力，在多个编程竞赛中超越了人类平均水平...",
        "link": "https://example.blog/alphacode-x-details",
        "pub_time": "2024-07-30T14:35:10Z",
        "source": "Example Tech Blog",
        "title": "AlphaCode X: 下一代 AI 编码助手",
        "type": "blog_post"
      },
      "time": "2024-07-30T14:35:10Z",
      "related": []
    },
    {
      "labels": {
        "content": "讨论了当前 LLM 在实际软件工程项目中落地所面临的挑战，包括成本、可控性和安全性问题。",
        "link": "https://another.blog/llm-in-swe-challenges",
        "pub_time": "2024-07-30T11:15:00Z",
        "source": "Another Tech Review",
        "title": "LLM 在软件工程中的应用：机遇与挑战",
        "type": "rss"
      },
      "time": "2024-07-30T11:15:00Z",
      "related": [
        {
          "labels": {
            "content": "一篇关于如何更经济有效地部署和微调大型语言模型的指南。",
            "link": "https://some.other.blog/cost-effective-llm",
            "pub_time": "2024-07-30T09:00:00Z",
            "source": "AI Infra Weekly",
            "title": "经济高效的 LLM 部署策略",
            "type": "rss"
          },
          "time": "2024-07-30T09:00:00Z",
          "related": []
        }
      ]
    }
  ]
}
```

## 4. 响应要求

Zenfeed 期望您的 Webhook 端点在成功接收并处理通知后，返回 HTTP `200 OK` 状态码。
如果 Zenfeed 收到任何非 `200` 的状态码，它会将该次通知尝试标记为失败，并可能根据重试策略进行重试 (具体重试行为取决于 Zenfeed 的内部实现)。

请确保您的端点能够及时响应，以避免超时。