> ## 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 пользовательского источника Push
> Зарегистрируйте источник и отправляйте в Living Security пакеты событий в формате JSON или CSV с помощью ключа доступа API с ограниченной областью действия.
Используйте Custom Push Source, когда система сама отправляет записи в 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. Создание ключа push-приема
Перейдите в **Настройки → Access Keys**, нажмите **Create Access Key** и выберите область действия **Push Ingest**. Сразу скопируйте сгенерированное значение: оно отображается только один раз.
Ключ привязан к одной организации Living Security. Для push-запроса заголовок организации не требуется. Сведения о ротации и отзыве см. в разделе [Ключи доступа API](/ru/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 строчных букв, цифр или дефисов; имя должно начинаться с буквы или цифры.
Зарегистрированное имя потока. Действуют те же правила, при этом также допускаются символы подчеркивания.
Передайте ключ доступа push-приема в виде `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
Задайте `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`, поэтому отправители webhook считают такую ошибку допускающей повтор. Ответ `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.
Создание, ротация и отзыв учетных данных с ограниченной областью действия.
Узнайте, как интерпретируемая активность интеграций используется в Сигналах.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.