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

# 自定义推送源 API

> 注册数据源，并使用限定范围的 API 访问密钥，将 JSON 或 CSV 事件批次发送至 Living Security。

当某个系统需要主动向 Living Security 发送记录，而不是由目录连接器轮询时，请使用自定义推送源。发送方可以将 JSON 数组或 CSV 文件提交至区域性 HTTPS 端点。

## 开始之前

您需要具备：

* 在 Living Security 中管理集成和访问密钥的权限
* 能够发起 HTTPS `POST` 请求的服务器端发送方
* 贵组织所在的 Living Security 区域
* 一个稳定的数据源名称和至少一个数据流名称

数据源名称和数据流名称是永久性的路由键。数据源名称必须为 1–64 个小写字母、数字或连字符。数据流名称还允许使用下划线。两者都必须以字母或数字开头。

<Warning>
  请将 API 访问密钥视为机密信息。不要将其放入浏览器代码，不要提交到源代码管理系统，也不要通过支持工单发送。
</Warning>

## 1. 注册数据源和数据流

<Steps>
  <Step title="打开自定义推送源">
    前往 **设置 → 集成 → 目录**，找到 **Custom Push Source**，然后选择 **添加**。
  </Step>

  <Step title="为数据源命名">
    输入数据源路由键和可选的描述。例如，请使用 `custom-phishing-sim`，而不要使用带空格的显示名称。
  </Step>

  <Step title="添加数据流">
    添加发送方将使用的每个数据流。数据源与数据流的组合必须在首次推送之前存在；未知的组合将返回 `404 Not Found`。
  </Step>

  <Step title="保存数据源">
    创建完成后，在 **设置 → 集成 → 已连接** 下打开该数据源。其 **Push via API** 视图会显示端点格式和最近的运行记录。
  </Step>
</Steps>

## 2. 创建推送摄取密钥

前往 **设置 → Access Keys**，选择 **Create Access Key**，然后选择 **Push Ingest** 范围。请立即复制生成的值；该值仅显示一次。

该密钥绑定到一个 Living Security 组织。推送请求无需组织标头。有关轮换和吊销，请参阅 [API 访问密钥](/zh-Hans/features/settings/api-keys)。

## 3. 选择区域端点

请使用与贵组织的 Living Security 对应的主机名：

| 区域 | 基础 URL |
| - | - |
| 美国 | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| 欧盟 | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

在其后附加 `/push-ingest/{integrationKey}/{streamName}`。路径区分大小写，且必须与已注册的数据源和数据流完全一致。

<ParamField path="integrationKey" type="string" required>
  已注册的数据源名称。请使用 1–64 个小写字母、数字或连字符，并以字母或数字开头。
</ParamField>

<ParamField path="streamName" type="string" required>
  已注册的数据流名称。规则相同，另外还允许使用下划线。
</ParamField>

<ParamField header="Authorization" type="string" required>
  将推送摄取访问密钥以 `Bearer <access-key>` 的形式发送。
</ParamField>

<ParamField header="Content-Type" type="string">
  JSON 请使用 `application/json`，CSV 请使用 `text/csv`。省略此标头时，服务器也可以检测 JSON 数组。
</ParamField>

<ParamField header="x-organization-id" type="string">
  可选的组织 UUID。访问密钥已确定所属组织。如果发送此标头，它必须与密钥所属的组织一致；它不能用于选择其他组织。
</ParamField>

### 请求正文

发送顶层的非空 JSON 对象数组，或带有标题行的 CSV 文件字节。不存在具名的 JSON 包装字段。每个批次最多可包含 10,000 条记录和 10 MB。

## 4. 发送 JSON 批次

发送元素均为对象的非空 JSON 数组。建议使用 `Content-Type: application/json`，许多发送产品也要求设置该标头，尽管 Living Security 在没有它的情况下也能检测数组正文。

<RequestExample>
  ```bash JSON batch theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: application/json' \
    --data '[
      {
        "email": "person@example.com",
        "event_at": "2026-09-21T14:30:00Z",
        "action": "reported"
      }
    ]'
  ```

  ```bash CSV file theme={null}
  curl --request POST \
    'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
    --header 'Authorization: Bearer <access-key>' \
    --header 'Content-Type: text/csv' \
    --data-binary '@events.csv'
  ```
</RequestExample>

请求成功时返回 `202 Accepted`。当 JSON 正文格式错误时，错误选项卡会显示 `400 Bad Request`：

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
    "recordsAccepted": 1,
    "integrationKey": "custom-phishing-sim",
    "streamName": "events"
  }
  ```

  ```json 400 Invalid JSON theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-09-22T14:30:00.000Z",
    "path": "/api/v1/push-ingest/custom-phishing-sim/events",
    "message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
    "error": "Bad Request"
  }
  ```
</ResponseExample>

接受表示该批次已存储以待异步处理，并不表示每条记录都已被解析为活动。
对于 `400` 示例，请更正 JSON，或使用 `Content-Type: text/csv` 发送 CSV，然后重试。

<ResponseField name="runId" type="string" required>
  此已接受批次的运行 ID。请保留它以检查处理状态。
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  已接受并存储的记录数。
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  本次推送所使用的数据源名称。
</ResponseField>

<ResponseField name="streamName" type="string" required>
  本次推送所使用的数据流名称。
</ResponseField>

## 改为发送 CSV

设置 `Content-Type: text/csv` 并发送文件字节，如上文 **CSV file** 请求示例所示。第一行提供字段名称。

布尔文本会转换为布尔值，普通数字文本会转换为数字。带前导零的值、不安全的大整数、日期和其他文本仍保留为字符串。空单元格会省略该字段。格式错误的行、引号不匹配以及 UTF-16 文件将被拒绝。

## 请求限制与重试

| 约定 | 当前值 |
| - | - |
| 最大记录数 | 每个请求 10,000 条 |
| 最大请求正文 | 10 MB |
| 每个组织的请求速率 | 每 60 秒 600 个请求 |

请将较大的导出数据拆分为同时满足这两项限制的批次。等待每个响应，并在发送方日志中保留返回的 `runId`。

| 响应 | 含义 | 发送方操作 |
| - | - | - |
| `202` | 批次已接受 | 记录 `runId`；不要立即重新发送 |
| `400` | 名称、JSON、CSV、记录数或正文无效 | 更正请求；不要在未修改的情况下重试 |
| `401` | 密钥缺失、已过期、已吊销或无效 | 更换密钥并使用 Bearer 标头 |
| `403` | 密钥缺少所需范围 | 创建具有 **Push Ingest** 范围的密钥 |
| `404` | 数据源或数据流未注册 | 注册完全一致的组合，或更正 URL |
| `413` | 请求正文超过 10 MB | 将批次拆分为更小的请求 |
| `429` | 临时的 IP 级别限流 | 如果存在 `Retry-After`，请遵守并退避 |
| `503` | 组织速率桶或限流器不可用 | 等待 `Retry-After`，然后重新发送相同的批次 |

正常的已认证组织限制返回 `503`，而不是 `429`，因此 webhook 发送方会将其视为可重试。`503` 在批次存储之前返回；在所述间隔之后重新发送同一批次不会产生重复的已接受运行。

## 验证数据流

打开自定义推送源并查看 **Push History**。确认数据流、记录数、密钥归属和处理状态。具有受维护解析器的数据随后可以转化为人员和标准化活动。没有解析器的数据会保持存储状态，但不会产生活动。

<Info>
  如果存在特定提供商的指南，请使用其中的确切字段名称和负载结构。成功的 `202` 仅证明传输成功，并不代表任意架构都能映射到 Living Security 活动。
</Info>

## 故障排查清单

* 从正确的数据源复制端点，并替换数据流占位符。
* 将访问密钥以 `Authorization: Bearer …` 的形式发送；不接受 `x-api-key`。
* 确认正文是顶层 JSON 数组，而不是单个对象或包裹记录的信封结构。
* 确认数据源和数据流的拼写，包括连字符、下划线和大小写。
* 在重新发送响应丢失的批次之前，请先查看 **Push History**。
* 联系 [Living Security 支持团队](mailto:support@livingsecurity.com) 时，请提供组织、数据源、数据流、请求时间、可用时的 `runId` 以及响应状态。请勿包含访问密钥或事件负载。

## 相关内容

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/zh-Hans/integrations/zscaler-zia-cloud-nss">
    使用确切的数据源、数据流、标头和 JSON 结构配置受支持的 Zscaler Web 日志源。
  </Card>

  <Card title="API 访问密钥" icon="key" href="/zh-Hans/features/settings/api-keys">
    创建、轮换和吊销限定范围的凭据。
  </Card>

  <Card title="信号数据源" icon="wave-pulse" href="/zh-Hans/signals/data-sources">
    了解经解析的集成活动如何支持信号。
  </Card>
</CardGroup>


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