> ## 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로 레코드를 직접 전송하는 경우에는 사용자 지정 푸시 소스(Custom Push Source)를 사용하십시오. 전송 측에서는 JSON 배열 또는 CSV 파일을 리전별 HTTPS 엔드포인트로 제출할 수 있습니다.

## 시작하기 전에

다음이 필요합니다.

* Living Security에서 연동 및 액세스 키를 관리할 수 있는 권한
* HTTPS `POST` 요청을 보낼 수 있는 서버 측 전송 프로그램
* 조직의 Living Security 리전
* 변경되지 않는 소스 이름과 하나 이상의 스트림 이름

소스 이름과 스트림 이름은 변경할 수 없는 라우팅 키입니다. 소스 이름은 소문자, 숫자 또는 하이픈으로 이루어진 1–64자여야 합니다. 스트림 이름에는 밑줄도 사용할 수 있습니다. 두 이름 모두 문자 또는 숫자로 시작해야 합니다.

<Warning>
  API 액세스 키는 비밀 정보로 취급하십시오. 브라우저 코드에 포함하거나, 소스 제어에 커밋하거나,
  지원 티켓으로 전송하지 마십시오.
</Warning>

## 1. 소스 및 스트림 등록

<Steps>
  <Step title="Custom Push Source 열기">
    **설정 → 통합 → 카탈로그**로 이동하여 **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 Access Keys](/ko/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 배열을 전송하십시오. Living Security는 이 헤더 없이도 배열 본문을 감지할 수 있지만, `Content-Type: application/json` 사용을 권장하며 많은 전송 제품에서 이를 필수로 요구합니다.

<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** 요청 예시와 같이 파일 바이트를 전송하십시오. 첫 번째 행이 필드 이름으로 사용됩니다.

불리언 텍스트는 불리언으로, 일반 숫자 텍스트는 숫자로 변환됩니다. 선행 0이 있는 값, 안전하지 않은 큰 정수, 날짜 및 기타 텍스트는 문자열로 유지됩니다. 빈 셀은 해당 필드를 생략합니다. 형식이 올바르지 않은 행, 짝이 맞지 않는 따옴표, 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` 동안 기다린 후 동일한 배치를 다시 전송하십시오 |

일반적인 인증된 조직 제한에서는 `429`이(가) 아니라 `503`이(가) 반환되므로 웹훅 전송 측에서는 이를 재시도 가능한 오류로 처리합니다. `503`은(는) 배치가 저장되기 전에 반환되며, 안내된 간격 이후 동일한 배치를 다시 전송해도 이미 수락된 실행이 중복되지 않습니다.

## 데이터 흐름 확인

Custom Push Source를 열고 **Push History**를 검토하십시오. 스트림, 레코드 수, 키 귀속 정보 및 처리 상태를 확인합니다. 유지 관리되는 해석기가 있는 데이터는 이후 사용자 및 정규화된 활동이 될 수 있습니다. 해석기가 없는 데이터는 저장은 되지만 활동을 생성하지 않습니다.

<Info>
  공급자별 가이드가 있는 경우 해당 가이드의 정확한 필드 이름과 페이로드 구조를 사용하십시오.
  성공적인 `202`은(는) 전달이 이루어졌음을 입증할 뿐, 임의의 스키마가 Living Security 활동에
  매핑된다는 것을 입증하는 것은 아닙니다.
</Info>

## 문제 해결 체크리스트

* 올바른 소스에서 엔드포인트를 복사하고 스트림 자리 표시자를 교체하십시오.
* 액세스 키를 `Authorization: Bearer …` 형식으로 전송하십시오. `x-api-key`은(는) 허용되지 않습니다.
* 본문이 단일 객체나 레코드를 감싸는 봉투 형태가 아니라 최상위 JSON 배열인지 확인하십시오.
* 하이픈, 밑줄, 대소문자를 포함하여 소스와 스트림의 철자를 확인하십시오.
* 응답이 유실된 배치를 다시 전송하기 전에 **Push History**를 검토하십시오.
* [Living Security Support](mailto:support@livingsecurity.com)에 문의할 때는 조직, 소스, 스트림, 요청 시간, 가능한 경우 `runId` 및 응답 상태를 포함하십시오. 액세스 키나 이벤트 페이로드는 포함하지 마십시오.

## 관련 항목

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/ko/integrations/zscaler-zia-cloud-nss">
    정확한 소스, 스트림, 헤더 및 JSON 구조로 지원되는 Zscaler 웹 로그 피드를 구성합니다.
  </Card>

  <Card title="API Access Keys" icon="key" href="/ko/features/settings/api-keys">
    범위가 지정된 자격 증명을 생성, 교체 및 폐기합니다.
  </Card>

  <Card title="Signal Data Sources" icon="wave-pulse" href="/ko/signals/data-sources">
    해석된 연동 활동이 신호를 지원하는 방식을 알아봅니다.
  </Card>
</CardGroup>


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