> ## 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 Sumber Push Kustom

> Daftarkan sumber dan kirim batch peristiwa JSON atau CSV ke Living Security menggunakan kunci akses API dengan cakupan terbatas.

Gunakan Custom Push Source ketika suatu sistem mengirimkan catatan ke Living Security, bukan di-polling oleh konektor Katalog. Pengirim dapat mengirimkan array JSON atau file CSV ke endpoint HTTPS regional.

## Sebelum Anda memulai

Anda memerlukan:

* izin untuk mengelola integrasi dan kunci akses di Living Security
* pengirim di sisi server yang dapat membuat permintaan HTTPS `POST`
* region Living Security untuk organisasi Anda
* nama sumber yang stabil dan setidaknya satu nama stream

Nama sumber dan nama stream adalah kunci perutean yang bersifat permanen. Nama sumber harus terdiri dari 1–64 huruf kecil, angka, atau tanda hubung. Nama stream juga mengizinkan garis bawah. Keduanya harus diawali dengan huruf atau angka.

<Warning>
  Perlakukan kunci akses API sebagai rahasia. Jangan menempatkannya di kode browser, menyimpannya
  ke dalam source control, atau mengirimkannya melalui tiket dukungan.
</Warning>

## 1. Daftarkan sumber dan stream

<Steps>
  <Step title="Buka Custom Push Source">
    Buka **Pengaturan → Integrasi → Katalog**, temukan **Custom Push Source**, lalu pilih **Tambahkan**.
  </Step>

  <Step title="Beri nama sumber">
    Masukkan kunci perutean sumber dan deskripsi opsional. Misalnya, gunakan `custom-phishing-sim` dan bukan nama tampilan yang mengandung spasi.
  </Step>

  <Step title="Tambahkan stream">
    Tambahkan setiap stream yang akan digunakan oleh pengirim. Pasangan sumber dan stream harus sudah ada sebelum push pertama; pasangan yang tidak dikenal akan menghasilkan `404 Not Found`.
  </Step>

  <Step title="Simpan sumber">
    Setelah dibuat, buka sumber tersebut di **Pengaturan → Integrasi → Terhubung**. Tampilan **Push via API** menunjukkan pola endpoint dan proses terbaru.
  </Step>
</Steps>

## 2. Buat kunci push-ingest

Buka **Pengaturan → Access Keys**, pilih **Create Access Key**, lalu pilih cakupan **Push Ingest**. Salin nilai yang dihasilkan segera; nilai ini hanya ditampilkan satu kali.

Kunci ini terikat pada satu organisasi Living Security. Permintaan push tidak memerlukan header organisasi. Lihat [Kunci Akses API](/id/features/settings/api-keys) untuk rotasi dan pencabutan.

## 3. Pilih endpoint regional

Gunakan hostname untuk organisasi Living Security Anda:

| Region | URL Dasar |
| - | - |
| Amerika Serikat | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Uni Eropa | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Tambahkan `/push-ingest/{integrationKey}/{streamName}`. Path ini peka huruf besar/kecil dan harus sama persis dengan sumber dan stream yang terdaftar.

<ParamField path="integrationKey" type="string" required>
  Nama sumber yang terdaftar. Gunakan 1–64 huruf kecil, angka, atau tanda hubung, diawali dengan huruf atau angka.
</ParamField>

<ParamField path="streamName" type="string" required>
  Nama stream yang terdaftar. Aturan yang sama berlaku, dan garis bawah juga diizinkan.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Kirim kunci akses push-ingest sebagai `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Gunakan `application/json` untuk JSON atau `text/csv` untuk CSV. Server juga dapat mendeteksi array JSON jika header ini dihilangkan.
</ParamField>

<ParamField header="x-organization-id" type="string">
  UUID organisasi (opsional). Kunci akses sudah menentukan organisasi. Jika Anda mengirim header ini, nilainya harus sesuai dengan organisasi milik kunci; header ini tidak dapat digunakan untuk memilih organisasi lain.
</ParamField>

### Isi permintaan

Kirim array JSON tingkat atas yang tidak kosong berisi objek, atau byte file CSV dengan baris header. Tidak ada field pembungkus JSON bernama. Setiap batch dapat berisi hingga 10,000 catatan dan 10 MB.

## 4. Kirim batch JSON

Kirim array JSON yang tidak kosong dengan elemen berupa objek. `Content-Type: application/json` direkomendasikan dan diwajibkan oleh banyak produk pengirim, meskipun Living Security dapat mendeteksi isi berupa array tanpa header tersebut.

<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>

Permintaan yang berhasil menghasilkan `202 Accepted`. Tab error menampilkan `400 Bad Request` ketika isi JSON tidak valid:

<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>

Penerimaan berarti batch telah disimpan untuk diproses secara asinkron. Hal ini tidak berarti setiap catatan sudah diinterpretasikan menjadi aktivitas.
Untuk contoh `400`, perbaiki JSON atau kirim CSV dengan `Content-Type: text/csv`, lalu coba lagi.

<ResponseField name="runId" type="string" required>
  ID proses untuk batch yang diterima ini. Simpan ID ini untuk memeriksa status pemrosesan.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Jumlah catatan yang diterima dan disimpan.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Nama sumber yang digunakan untuk push ini.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Nama stream yang digunakan untuk push ini.
</ResponseField>

## Kirim CSV sebagai alternatif

Atur `Content-Type: text/csv` dan kirim byte file, seperti yang ditunjukkan pada contoh permintaan **CSV file** di atas. Baris pertama menyediakan nama field.

Teks boolean diubah menjadi boolean dan teks numerik biasa diubah menjadi angka. Nilai dengan nol di depan, bilangan bulat besar yang tidak aman, tanggal, dan teks lainnya tetap berupa string. Sel kosong menyebabkan field tersebut dihilangkan. Baris yang tidak valid, tanda kutip yang tidak seimbang, dan file UTF-16 akan ditolak.

## Batas permintaan dan percobaan ulang

| Kontrak | Nilai saat ini |
| - | - |
| Catatan maksimum | 10,000 per permintaan |
| Isi permintaan maksimum | 10 MB |
| Laju permintaan per organisasi | 600 permintaan per 60 detik |

Pecah ekspor yang lebih besar menjadi batch yang memenuhi kedua batas tersebut. Tunggu setiap respons dan simpan `runId` yang dikembalikan di log pengirim.

| Respons | Arti | Tindakan pengirim |
| - | - | - |
| `202` | Batch diterima | Catat `runId`; jangan langsung mengirim ulang |
| `400` | Nama, JSON, CSV, jumlah catatan, atau isi tidak valid | Perbaiki permintaan; jangan coba lagi tanpa perubahan |
| `401` | Kunci tidak ada, kedaluwarsa, dicabut, atau tidak valid | Ganti kunci dan gunakan header Bearer |
| `403` | Kunci tidak memiliki cakupan yang diperlukan | Buat kunci dengan cakupan **Push Ingest** |
| `404` | Sumber atau stream tidak terdaftar | Daftarkan pasangan yang tepat atau perbaiki URL |
| `413` | Isi permintaan melebihi 10 MB | Pecah batch menjadi permintaan yang lebih kecil |
| `429` | Pembatasan sementara pada tingkat IP | Patuhi `Retry-After` jika ada dan lakukan back off |
| `503` | Bucket laju organisasi atau pembatas laju tidak tersedia | Tunggu `Retry-After`, lalu kirim ulang batch yang sama |

Batas organisasi terautentikasi yang normal menghasilkan `503`, bukan `429`, sehingga pengirim webhook memperlakukannya sebagai kondisi yang dapat dicoba ulang. `503` dikembalikan sebelum batch disimpan; mengirim ulang batch yang sama setelah interval yang dinyatakan tidak menduplikasi proses yang sudah diterima.

## Verifikasi aliran data

Buka Custom Push Source dan tinjau **Push History**. Konfirmasikan stream, jumlah catatan, atribusi kunci, dan status pemrosesan. Data dengan interpreter yang dipelihara kemudian dapat menjadi orang dan aktivitas yang dinormalisasi. Data tanpa interpreter tetap tersimpan tetapi tidak menghasilkan aktivitas.

<Info>
  Gunakan nama field dan bentuk payload yang tepat dari panduan khusus penyedia
  jika tersedia. `202` yang berhasil membuktikan pengiriman, bukan bahwa skema
  sembarang dipetakan ke aktivitas Living Security.
</Info>

## Daftar periksa pemecahan masalah

* Salin endpoint dari sumber yang benar dan ganti placeholder stream.
* Kirim kunci akses sebagai `Authorization: Bearer …`; `x-api-key` tidak diterima.
* Pastikan isi permintaan adalah array JSON tingkat atas, bukan objek tunggal atau pembungkus di sekitar catatan.
* Pastikan ejaan sumber dan stream, termasuk tanda hubung, garis bawah, dan huruf besar/kecil.
* Tinjau **Push History** sebelum mengirim ulang batch yang responsnya hilang.
* Saat menghubungi [Dukungan Living Security](mailto:support@livingsecurity.com), sertakan organisasi, sumber, stream, waktu permintaan, `runId` jika tersedia, dan status respons. Jangan sertakan kunci akses atau payload peristiwa.

## Terkait

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/id/integrations/zscaler-zia-cloud-nss">
    Konfigurasikan feed log web Zscaler yang didukung dengan sumber, stream, header, dan bentuk JSON yang tepat.
  </Card>

  <Card title="Kunci Akses API" icon="key" href="/id/features/settings/api-keys">
    Buat, rotasi, dan cabut kredensial dengan cakupan terbatas.
  </Card>

  <Card title="Sumber Data Sinyal" icon="wave-pulse" href="/id/signals/data-sources">
    Pelajari bagaimana aktivitas integrasi yang diinterpretasikan mendukung sinyal.
  </Card>
</CardGroup>


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