> ## 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.
# Custom Push Source API
> Зареєструйте джерело та надсилайте до Living Security пакети подій у форматі JSON або CSV за допомогою ключа доступу API з обмеженою областю дії.
Використовуйте Custom Push Source, коли система надсилає записи до Living Security, а не опитується конектором із Catalog. Відправник може передавати масиви JSON або файли CSV на регіональну кінцеву точку HTTPS.
## Перш ніж почати
Вам потрібні:
* дозвіл на керування інтеграціями та ключами доступу в Living Security
* серверний відправник, який може виконувати HTTPS-запити `POST`
* регіон Living Security для вашої організації
* стабільна назва джерела та принаймні одна назва потоку
Назви джерел і потоків є постійними ключами маршрутизації. Назва джерела має містити від 1 до 64 малих літер, цифр або дефісів. У назвах потоків також дозволено символи підкреслення. Обидві назви мають починатися з літери або цифри.
Ставтеся до ключа доступу API як до секрету. Не розміщуйте його в коді браузера, не додавайте
до системи керування версіями та не надсилайте в запиті до служби підтримки.
## 1. Зареєструйте джерело та потоки
Перейдіть до **Settings → Integrations → Catalog**, знайдіть **Custom Push Source** і виберіть **Add**.
Введіть ключ маршрутизації джерела та, за потреби, опис. Наприклад, використовуйте `custom-phishing-sim` замість відображуваної назви з пробілами.
Додайте кожен потік, який використовуватиме відправник. Пара «джерело — потік» має існувати до першого надсилання; невідома пара повертає `404 Not Found`.
Після створення відкрийте джерело в розділі **Settings → Integrations → Connected**. Його вигляд **Push via API** показує шаблон кінцевої точки та останні запуски.
## 2. Створіть ключ для надсилання даних
Перейдіть до **Settings → Access Keys**, виберіть **Create Access Key** і оберіть область дії **Push Ingest**. Негайно скопіюйте згенероване значення; воно відображається лише один раз.
Ключ прив’язаний до однієї організації Living Security. Запит на надсилання не потребує заголовка організації. Інформацію про ротацію та відкликання див. у розділі [API Access Keys](/uk/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}`. Шлях чутливий до регістру та має точно збігатися із зареєстрованими джерелом і потоком.
Зареєстрована назва джерела. Використовуйте від 1 до 64 малих літер, цифр або дефісів, починаючи з літери або цифри.
Зареєстрована назва потоку. Діють ті самі правила, а також дозволено символи підкреслення.
Надсилайте ключ доступу для надсилання даних у форматі `Bearer `.
Використовуйте `application/json` для JSON або `text/csv` для CSV. Сервер також може розпізнати масив JSON, якщо цей заголовок пропущено.
Необов’язковий UUID організації. Організацію вже визначає ключ доступу. Якщо ви надсилаєте цей заголовок, він має збігатися з організацією ключа; за його допомогою не можна вибрати іншу організацію.
### Тіло запиту
Надішліть непорожній масив JSON верхнього рівня, що складається з об’єктів, або байти файлу CSV із рядком заголовків. Іменованого поля-обгортки для JSON немає. Кожен пакет може містити до 10,000 записів і до 10 MB.
## 4. Надішліть пакет JSON
Надішліть непорожній масив JSON, елементами якого є об’єкти. `Content-Type: application/json` рекомендований і вимагається багатьма продуктами-відправниками, хоча Living Security може розпізнати тіло-масив і без нього.
```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 ' \
--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 ' \
--header 'Content-Type: text/csv' \
--data-binary '@events.csv'
```
Успішний запит повертає `202 Accepted`. Вкладка помилки показує `400 Bad Request`, якщо тіло JSON сформовано неправильно:
```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"
}
```
Прийняття означає, що пакет збережено для асинхронної обробки. Це не означає, що кожен запис уже інтерпретовано в активність.
Для прикладу `400` виправте JSON або надішліть CSV із `Content-Type: text/csv` і повторіть спробу.
Ідентифікатор запуску для цього прийнятого пакета. Збережіть його, щоб перевіряти стан обробки.
Кількість прийнятих і збережених записів.
Назва джерела, використана для цього надсилання.
Назва потоку, використана для цього надсилання.
## Надсилання CSV замість JSON
Задайте `Content-Type: text/csv` і надішліть байти файлу, як показано в прикладі запиту **CSV file** вище. Перший рядок задає назви полів.
Текстові булеві значення перетворюються на булевий тип, а звичайний числовий текст — на число. Значення з ведучими нулями, небезпечно великі цілі числа, дати та інший текст залишаються рядками. Порожні клітинки пропускають відповідне поле. Неправильно сформовані рядки, незбалансовані лапки та файли UTF-16 відхиляються.
## Обмеження запитів і повторні спроби
| Умова | Поточне значення |
| - | - |
| Максимальна кількість записів | 10,000 на запит |
| Максимальний розмір тіла запиту | 10 MB |
| Частота запитів на організацію | 600 запитів за 60 секунд |
Розділяйте більші експорти на пакети, що відповідають обом обмеженням. Чекайте на кожну відповідь і зберігайте отриманий `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`, тому відправники вебгуків вважають його таким, що допускає повторну спробу. `503` повертається до збереження пакета; повторне надсилання того самого пакета після вказаного інтервалу не дублює прийнятий запуск.
## Перевірте потік даних
Відкрийте Custom Push Source і перегляньте **Push History**. Переконайтеся в правильності потоку, кількості записів, атрибуції ключа та стану обробки. Дані з підтримуваним інтерпретатором згодом можуть стати користувачами та нормалізованою активністю. Дані без інтерпретатора залишаються збереженими, але не створюють активності.
Використовуйте точні назви полів і структуру даних із посібника для конкретного постачальника,
якщо такий існує. Успішний `202` підтверджує доставку, але не те, що довільна схема
зіставляється з активністю Living Security.
## Контрольний список усунення несправностей
* Скопіюйте кінцеву точку з потрібного джерела та замініть заповнювач потоку.
* Надсилайте ключ доступу як `Authorization: Bearer …`; `x-api-key` не приймається.
* Переконайтеся, що тіло є масивом JSON верхнього рівня, а не окремим об’єктом чи обгорткою навколо записів.
* Перевірте написання джерела й потоку, зокрема дефіси, підкреслення та регістр.
* Перегляньте **Push History**, перш ніж повторно надсилати пакет, відповідь на який було втрачено.
* Звертаючись до [служби підтримки Living Security](mailto:support@livingsecurity.com), вкажіть організацію, джерело, потік, час запиту, `runId` (за наявності) та статус відповіді. Не додавайте ключ доступу або корисне навантаження подій.
## Пов’язані матеріали
Налаштуйте підтримуваний канал вебжурналів Zscaler з точним джерелом, потоком, заголовками та структурою JSON.
Створюйте, ротуйте та відкликайте облікові дані з обмеженою областю дії.
Дізнайтеся, як інтерпретована активність інтеграцій підтримує Signals.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.