> ## 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-Hant/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-Hant/integrations/zscaler-zia-cloud-nss">
    使用確切的來源、串流、標頭與 JSON 格式，設定受支援的 Zscaler 網頁記錄摘要。
  </Card>

  <Card title="API 存取金鑰" icon="key" href="/zh-Hant/features/settings/api-keys">
    建立、輪替及撤銷限定範圍的憑證。
  </Card>

  <Card title="訊號資料來源" icon="wave-pulse" href="/zh-Hant/signals/data-sources">
    瞭解經解讀的整合活動如何支援訊號。
  </Card>
</CardGroup>


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