自訂推送來源 API

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"
    }
  ]'

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'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "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"
}

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"
    }
  ]'

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'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "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"
}

當系統需要主動將記錄傳送至 Living Security，而非由目錄連接器輪詢時，請使用自訂推送來源。傳送端可將 JSON 陣列或 CSV 檔案提交至區域 HTTPS 端點。

開始之前

您需要具備：

在 Living Security 中管理整合與存取金鑰的權限
可發出 HTTPS POST 請求的伺服器端傳送程式
貴組織所在的 Living Security 區域
固定的來源名稱，以及至少一個串流名稱

來源名稱與串流名稱為永久性的路由金鑰。來源名稱必須為 1–64 個小寫字母、數字或連字號。串流名稱另允許使用底線。兩者都必須以字母或數字開頭。

請將 API 存取金鑰視為機密。請勿將其放入瀏覽器程式碼、提交至原始碼控管，或透過支援工單傳送。

1. 註冊來源與串流

開啟自訂推送來源

前往 設定 → 集成 → 目錄，找到 Custom Push Source，然後選取添加。

為來源命名

輸入來源路由金鑰及選用的說明。例如，請使用 custom-phishing-sim，而非含有空格的顯示名稱。

新增串流

新增傳送端將使用的每個串流。來源與串流配對必須在第一次推送之前已存在；未知的配對會傳回 404 Not Found。

儲存來源

建立完成後，請在 設定 → 集成 → 已連接 下開啟該來源。其 Push via API 檢視會顯示端點格式與近期執行紀錄。

2. 建立推送擷取金鑰

前往 設定 → Access Keys，選取 Create Access Key，然後選擇 Push Ingest 範圍。請立即複製產生的值；該值僅會顯示一次。此金鑰綁定單一 Living Security 組織。推送請求不需要組織標頭。有關輪替與撤銷，請參閱 API 存取金鑰。

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}。路徑區分大小寫，且必須與已註冊的來源和串流完全一致。

string

必填

已註冊的來源名稱。請使用 1–64 個小寫字母、數字或連字號，並以字母或數字開頭。

string

必填

已註冊的串流名稱。適用相同規則，並且另允許使用底線。

string

必填

將推送擷取存取金鑰以 Bearer <access-key> 的形式傳送。

string

JSON 請使用 application/json，CSV 請使用 text/csv。省略此標頭時，伺服器也可偵測 JSON 陣列。

string

選用的組織 UUID。存取金鑰已決定組織。若您傳送此標頭，其值必須與金鑰所屬組織相符；它無法用來選擇其他組織。

請求本文

請傳送最上層、非空的 JSON 物件陣列，或含標題列的 CSV 檔案位元組。沒有具名的 JSON 包裝欄位。每個批次最多可包含 10,000 筆記錄與 10 MB。

4. 傳送 JSON 批次

請傳送非空的 JSON 陣列，其元素須為物件。建議使用 Content-Type: application/json，且許多傳送產品都要求使用，即使 Living Security 在沒有它的情況下也能偵測陣列本文。

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"
    }
  ]'

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'

成功的請求會傳回 202 Accepted。當 JSON 本文格式錯誤時，錯誤索引標籤會顯示 400 Bad Request：

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "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"
}

接受表示批次已儲存以供非同步處理，並不表示每筆記錄都已被解讀為活動。針對 400 範例，請修正 JSON，或改以 Content-Type: text/csv 傳送 CSV，然後重試。

string

必填

此已接受批次的執行 ID。請保留該值以檢查處理狀態。

number

必填

已接受並儲存的記錄數量。

string

必填

此次推送所使用的來源名稱。

string

必填

此次推送所使用的串流名稱。

改為傳送 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。確認串流、記錄數、金鑰歸屬與處理狀態。具有維護中解譯器的資料隨後可成為人員與標準化活動。沒有解譯器的資料會保持儲存狀態，但不會產生活動。

若有供應商專屬指南，請使用其中確切的欄位名稱與酬載格式。成功的 202 僅證明傳遞成功，並不代表任意結構描述都能對應至 Living Security 活動。

疑難排解檢查清單

從正確的來源複製端點，並替換串流預留位置。
將存取金鑰以 Authorization: Bearer … 的形式傳送；系統不接受 x-api-key。
確認本文為最上層 JSON 陣列，而非單一物件或包覆記錄的外層結構。
確認來源與串流的拼寫，包括連字號、底線及大小寫。
若某批次的回應遺失，請在重新傳送前檢視 Push History。
聯絡 Living Security 支援團隊時，請提供組織、來源、串流、請求時間、（如有）runId，以及回應狀態。請勿附上存取金鑰或事件酬載。

Zscaler ZIA Cloud NSS

使用確切的來源、串流、標頭與 JSON 格式，設定受支援的 Zscaler 網頁記錄摘要。

API 存取金鑰

建立、輪替及撤銷限定範圍的憑證。

訊號資料來源

瞭解經解讀的整合活動如何支援訊號。

整合

整合設定

目錄

外送管道

開始之前

1. 註冊來源與串流

2. 建立推送擷取金鑰

3. 選擇區域端點

請求本文

4. 傳送 JSON 批次

改為傳送 CSV

請求限制與重試

驗證資料流

疑難排解檢查清單

相關內容

Zscaler ZIA Cloud NSS

API 存取金鑰

訊號資料來源

整合

整合設定

目錄

外送管道

​開始之前

​1. 註冊來源與串流

​2. 建立推送擷取金鑰

​3. 選擇區域端點

​請求本文

​4. 傳送 JSON 批次

​改為傳送 CSV

​請求限制與重試

​驗證資料流

​疑難排解檢查清單

​相關內容

Zscaler ZIA Cloud NSS

API 存取金鑰

訊號資料來源

開始之前

1. 註冊來源與串流

2. 建立推送擷取金鑰

3. 選擇區域端點

請求本文

4. 傳送 JSON 批次

改為傳送 CSV

請求限制與重試

驗證資料流

疑難排解檢查清單

相關內容