Журналы аудита

Отслеживайте поддерживаемые действия в организации Enterprise с помощью журналов аудита, получая события через вебхук или API аудита только для чтения.

Обзор

Журналы аудита доступны организациям Enterprise с 50 и более местами или хотя бы с одним местом Enterprise Max. Администраторы могут использовать их для расследования действий и отслеживания административных изменений.

Вы можете получать события через вебхук, запрашивать сохранённые события через API аудита или использовать оба способа. API не требует вебхука и не меняет существующую конфигурацию вебхука.

Выберите способ доступа к журналам аудита

Способ	Передача	Содержимое
Вебхук	HTTP POST на вашу конечную точку	Сведения и содержимое событий, если они записаны
API аудита	Запросы от вашей интеграции	Записанные метаданные и содержимое событий с сокрытием учётных данных

Таблица 1. Доставка через вебхук и получение через API аудита.

Для событий, доступных обоими способами, API возвращает записанные метаданные, включая текст запроса, текст ответа и имена файлов, если они есть. При обоих способах текст запроса и ответа ограничен первыми 500 символами. Также действует описанное в этой статье исключение для comet_agent_action.

Полезные нагрузки не полностью идентичны: API использует другие имена полей верхнего уровня и скрывает учётные данные в некоторых изменениях настроек вебхука. Подробнее об области действия этого сокрытия см. в разделе Конфиденциальность и безопасность данных.

Вебхук обеспечивает более быструю доставку. Для API не гарантируется интервал обновления, поэтому его нельзя считать гарантированно полной копией потока событий вебхука.

Журналы аудита фиксируют не все действия. Ни один из способов не записывает изменения тарифного уровня мест, выполненные через SCIM, который синхронизирует состав участников с вашим поставщиком удостоверений, или через инструменты массовых операций. Добавление и удаление участников при массовых операциях с CSV также не фиксируется.

Перед началом

• Убедитесь, что организация соответствует указанным выше требованиям к местам.
• Попросите администратора с доступом к настройкам организации включить ведение журнала.
• Для управления ключами API используйте роль, которой разрешены и просмотр журналов аудита, и доступ к API Perplexity. Встроенная роль администратора имеет оба разрешения; пользовательским ролям тоже можно предоставить оба.
• Убедитесь, что для вашей организации включено создание ключей API. Если оно не включено, обратитесь к команде по работе с вашим аккаунтом, чтобы запросить доступ.
• Для доставки через вебхук подготовьте конечную точку HTTPS и значение для аутентификации.

Сведения о настройках организации и разрешениях API см. в статье Роли и разрешения Enterprise. Ключи API аудита отличаются от обычных ключей API Perplexity и ключей API аналитики.

Конфиденциальность и безопасность данных

При обоих способах данные могут содержать персональную информацию и записанное содержимое, а не только идентификаторы действий. В зависимости от события метаданные могут включать текст запросов и ответов, имена файлов, адреса электронной почты затронутых участников, значения настроек организации и сведения о задачах Perplexity Computer.

При изменении токена аутентификации вебхука API заменяет записанные старое и новое значения токена на [REDACTED]. При изменении URL-адреса вебхука он удаляет учётные данные, путь, строку запроса и фрагмент URL, по возможности сохраняя origin адреса назначения; очищенные значения по-прежнему можно определить как очищенные.

Эти правила сокрытия действуют для ответов API, относящихся к указанным настройкам вебхука, но не для доставки через вебхук или сохранённых событий. Они не удаляют из метаданных API другую записанную персональную информацию или содержимое.

Ограничьте доступ к собранным журналам в соответствии с политиками конфиденциальности вашей организации. Храните URL-адреса вебхуков, значения для аутентификации и ключи API в тайне и отзывайте ключи, которые больше не нужны.

Общие правила работы с данными в Enterprise описаны в статье Хранение данных и конфиденциальность для Enterprise. В Центре доверия представлена документация по безопасности и соответствию требованиям, а Дополнение об обработке данных определяет договорные условия обработки данных, если оно включено в ваше соглашение.

Настройки удаления сеансов и файлов из статьи Хранение данных для корпоративных клиентов не определяют срок хранения данных API аудита. Рассматривайте политику вашей организации по хранению экспортированных журналов отдельно от хранения событий аудита в Perplexity.

Срок хранения событий API аудита здесь не указан. Своевременно собирайте события и храните копии согласно политике вашей организации; уточните применимые условия хранения у команды по работе с вашим аккаунтом.

Включение журналов аудита

1. Перейдите в Настройки организации.

2. Откройте Данные и конфиденциальность.

3. В разделе Настройки журнала аудита включите переключатель ведения журнала аудита.

   

   Рисунок 1. Переключатель ведения журнала в настройках журнала аудита.

Если вы используете только API, оставьте поля вебхука пустыми и перейдите к разделу Запрос журналов аудита через API. Для доставки через вебхук выполните следующие действия:

1. Введите адрес вашей конечной точки HTTPS в поле URL-адрес вебхука.

   

   Рисунок 2. Настройки URL-адреса вебхука и заголовка авторизации.

2. Нажмите Сохранить рядом с полем URL-адрес вебхука.

3. Если конечная точка требует аутентификации, введите значение в поле Заголовок Authorization.

4. Нажмите Сохранить рядом с полем Заголовок Authorization.

Если вы не укажете схему авторизации, введённое значение будет отправлено как токен Bearer. О двух поддерживаемых форматах см. в разделе Аутентификация вебхука.

После поддерживаемого действия убедитесь, что принимающая конечная точка получает событие вебхука и возвращает ответ HTTP 2xx.

Запрос журналов аудита через API

Используйте API аудита только для чтения, чтобы получать сохранённые события для расследований или загрузки в систему управления информацией и событиями безопасности (SIEM). Вы сами определяете, когда интеграция запрашивает события; конечная точка для входящих вебхуков не требуется.

Создание ключа API аудита

1. Откройте Настройки организации, перейдите в раздел API Enterprise и найдите область API аудита.

2. Нажмите кнопку создания ключа.

   

   Рисунок 3. Элементы управления ключами API аудита в настройках организации.

3. Укажите название ключа, например SIEM production.

   

   Рисунок 4. Укажите название ключа API аудита перед его созданием.

4. Нажмите кнопку создания ключа.

5. Когда появится подтверждение создания ключа API, скопируйте секретное значение.

6. Сохраните секретное значение в безопасном месте. Оно показывается только один раз.

Если раздел отсутствует, попросите администратора проверить оба необходимых разрешения. Если кнопка создания ключа недоступна, следуйте сообщению на странице: включите ведение журнала аудита, если оно выключено, или обратитесь к команде по работе с вашим аккаунтом, если создание ключей API для организации не включено.

Ключи принадлежат организации, а не создавшему их пользователю. Удаление этого пользователя или изменение его разрешений не отзывает ключ. Отзывайте ключи, которые больше не нужны; отзыв немедленно прекращает запросы с этим ключом.

Подключение интеграции

Для аутентификации интеграции используйте ключ API аудита. Каждый ключ может читать события аудита только своей организации и не может обращаться к API моделей.

Конечную точку, примеры аутентификации, параметры запросов, поля ответов, пагинацию, ограничения частоты запросов и ошибки см. в документации API аудита. Используйте этот справочник разработчика при создании или обслуживании системы сбора событий. Запрос может использовать after_id либо before_id, но не оба параметра одновременно.

Содержимое и охват событий

Метаданные API используют поля конкретного события, сохранённые для получения через API. Они могут отличаться от метаданных вебхука, в том числе для comet_agent_action, как описано ниже. Значения могут включать текст, вложенные объекты, имена и адреса электронной почты; состав полей зависит от события и от того, что было записано. У некоторых событий нет метаданных.

Общие метаданные не делают внешние структуры API и вебхука взаимозаменяемыми и не гарантируют фиксацию всех действий. Сокрытие учётных данных применяется только к API; ограничения текста и пробелы в регистрации относятся к обоим способам.

Для comet_agent_action метаданные API содержат только action, если это значение записано. Поля url и action_params отправляются только через вебхуки и не сохраняются для получения через API.

Каждое успешное чтение через API создаёт событие audit_events_accessed, доступное через API, но не через вебхук. При проверке доступа явно запрашивайте этот тип событий; он исключён из потока API по умолчанию.

Доступность данных

Доступная история начинается с момента включения ведения журнала аудита в организации; более ранние действия задним числом не добавляются. Сохранённая история не охватывает период до 16 июля 2026 года.

Отключение ведения журнала аудита прекращает запись новых событий, а запросы API начинают возвращать 404. При этом ключи не отзываются, а сохранённые события не удаляются немедленно. Неотозванные ключи снова работают после повторного включения ведения журнала; отозвать ключи можно и при выключенном ведении журнала.

Проверка результата

Используйте пример запроса из документации API аудита, чтобы убедиться, что интеграция получает успешный ответ. Пустой список событий может означать, что ни одно событие не соответствует выбранному периоду и типу; сам по себе он не указывает на ошибку аутентификации.

Аутентификация вебхука

Вы можете защитить конечную точку вебхука с помощью токена Bearer или полного значения авторизации. Настройте значение, которое ожидает ваша принимающая конечная точка.

Токен Bearer

Укажите токен без префикса, например YOUR_WEBHOOK_TOKEN. Perplexity добавит перед ним Bearer и отправит Authorization: Bearer YOUR_WEBHOOK_TOKEN.

Пользовательский заголовок авторизации

Укажите полное значение авторизации, включающее схему. Например, Splunk YOUR_HEC_TOKEN будет отправлено как Authorization: Splunk YOUR_HEC_TOKEN.

Доставка через вебхук

Формат запроса

Журналы аудита доставляются на URL-адрес вашего вебхука в виде HTTP-запросов POST. Тело запроса использует application/json.

Заголовок аутентификации

Если вы настроили значение для аутентификации, Perplexity включает его в заголовок Authorization. Форматы Bearer и пользовательских схем описаны в разделе Аутентификация вебхука.

Обработка ответов

Ваша конечная точка вебхука должна возвращать ответ HTTP 2xx для подтверждения получения в течение 1 секунды. Perplexity регистрирует ошибки доставки, включая ответы HTTP 4xx и 5xx, но не повторяет автоматически неудачные доставки или доставки с истёкшим временем ожидания. Отслеживайте сбои и пропущенные события на принимающей конечной точке.

Чтобы восстановить пропущенную доставку, запросите через API события за соответствующий период. Восстановить можно только события, которые были успешно сохранены и всё ещё доступны; API не может воссоздать события, которые никогда не записывались.

Схема журнала аудита вебхука

События вебхука используют приведённые ниже поля. Другие имена полей верхнего уровня API см. в документации API аудита; сравнение метаданных приведено в разделе Запрос журналов аудита через API.

Поле	Тип	Обязательно	Описание
uuid	Строка	Да	Идентификатор события
timestamp	Строка	Да	Метка времени RFC 3339
event_type	Строка	Да	Тип события
user_email	Строка	Да	Электронная почта участника, выполнившего действие
ip_address	Строка	Да	Адрес клиента или маркер, не являющийся IP-адресом
user_agent	Строка	Да	User-Agent клиента
session_id	Строка или null	Нет	Идентификатор связанных событий
user_id	Строка или null	Нет	Идентификатор пользователя, если записан
metadata	Объект или null	Нет	Данные конкретного события

Таблица 2. Поля полезной нагрузки вебхука.

Обязательное строковое поле может быть пустым, если значение не было записано. Не следует считать каждое значение ip_address IP-адресом.

Типы событий

В следующих таблицах описаны документированные типы событий вебхука. Это не гарантирует, что каждое действие записывается или что каждый тип доступен обоими способами. Для событий, доступных обоими способами, API возвращает записанные метаданные с учётом описанных выше правил сокрытия. Также действует описанное в этой статье исключение для comet_agent_action.

События активности пользователей

Тип события	Описание
login	Успешный вход
query	Отправлен поисковый запрос
answer_generated	Возвращён ответ
file_upload	Файл загружен в запрос или проект
file_download	Файл скачан из проекта
file_delete	Файл удалён из запроса или проекта

Таблица 3. События активности пользователей.

События запросов могут включать metadata.attachments с file_uuid и file_name для каждого прикреплённого файла. Оба способа могут возвращать эти вложенные поля, если они записаны.

События тредов

Тип события	Описание
thread_forked	Тред скопирован
thread_exported	Тред экспортирован
thread_shared	Предоставлен доступ к треду
thread_deleted	Тред удалён

Таблица 4. События тредов.

События участников

Тип события	Описание
member_invited	Участник приглашён
member_invite_rescinded	Ожидающее приглашение отозвано
member_removed	Участник удалён
member_role_changed	Роль участника изменена

Таблица 5. События участников.

События организации

Тип события	Описание
organization_settings_update	Настройка организации изменена

Таблица 6. События организации.

События ролей и групп

Тип события	Описание
role_created	Пользовательская роль создана
role_updated	Сведения о роли или её разрешения обновлены
role_deleted	Пользовательская роль удалена
role_users_changed	Пользователи добавлены в роль или удалены из неё
role_groups_changed	Группы добавлены в роль или удалены из неё
group_created	Группа пользователей создана
group_deleted	Группа пользователей удалена
group_members_changed	Состав группы изменён

Таблица 7. События ролей и групп.

Для role_users_changed и role_groups_changed метаданные могут включать поле action со значением added или removed. Используйте это поле, чтобы отличить добавление от удаления.

События агента Comet

Тип события	Описание
comet_agent_action	Автоматическое действие Comet

Таблица 8. События агента Comet.

События коннекторов

Тип события	Описание
connector_connected	Сторонний коннектор подключён
connector_disconnected	Сторонний коннектор отключён

Таблица 9. События коннекторов.

События Computer

Тип события	Описание
computer_task_started	Задача Computer запущена
computer_agent_action	Автоматическое действие в ходе задачи
computer_task_completed	Задача успешно завершена
computer_task_error	Задача завершилась с ошибкой

Таблица 10. События Computer.

Пример полезной нагрузки вебхука

Этот иллюстративный пример полезной нагрузки JSON представляет событие запроса, доставленное на обычный вебхук. Это не ответ API аудита.

{
  "uuid": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
  "timestamp": "2026-10-28T09:05:31+00:00",
  "event_type": "query",
  "user_email": "[e-mail]",
  "ip_address": "203.0.113.45",
  "user_agent": "ExampleClient/1.0",
  "session_id": "query_abc123",
  "metadata": {
    "query_str": "What are the best practices for API security?"
  }
}

Форматирование для отдельных платформ

Вебхуки Slack

Для URL-адреса вебхука, начинающегося с https://hooks.slack.com, Perplexity использует формат Block Kit от Slack. Массив blocks содержит разделы с типом события, сведениями об участнике и клиенте, а также метаданными события, если они есть.

В названиях типов событий каждое слово начинается с заглавной буквы, а подчёркивания удаляются. При форматировании для Slack отдельные значения метаданных сокращаются до 500 символов, а раздел метаданных до 2500 символов; для длинных значений выводится уведомление о сокращении.

Splunk HTTP Event Collector

Когда значение авторизации начинается с Splunk, Perplexity помещает полезную нагрузку в объект event для HTTP Event Collector (HEC) от Splunk. Этот иллюстративный пример показывает внешнюю структуру:

{
  "event": {
    "uuid": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "timestamp": "2026-10-28T09:05:31+00:00",
    "event_type": "login",
    "user_email": "[e-mail]",
    "ip_address": "203.0.113.45",
    "user_agent": "ExampleClient/1.0",
    "session_id": null,
    "metadata": {}
  }
}

Обычные вебхуки

Для других адресов назначения вебхука Perplexity отправляет стандартную полезную нагрузку JSON без внешней структуры, специфичной для платформы. Формат см. в разделе Пример полезной нагрузки вебхука.

Типичные сценарии работы с вебхуками

Отслеживание сеансов исследования

Используйте session_id, чтобы сопоставить запрос с ответом. В этих шагах используются имена полей вебхука; имена полей верхнего уровня API отличаются, даже если метаданные событий совпадают.

1. Найдите событие запроса

   Прочитайте query_str в метаданных события. Сохраните его session_id, чтобы найти связанные события.

2. Сопоставьте событие ответа

   Найдите событие answer_generated с тем же session_id. Если значение записано, answer содержит не более первых 500 символов ответа; рядом в поле model указана использованная модель.

Мониторинг доступа к файлам

Используйте идентификаторы файлов, чтобы сопоставлять загрузки и скачивания. При обоих способах метаданные событий могут включать записанные сведения о файлах и проектах.

1. Найдите загрузку файла

   Прочитайте file_uuid события загрузки. Сохраните идентификатор для сравнения с последующими событиями.

2. Сопоставьте скачивания файла

   Найдите события скачивания с тем же file_uuid. Используйте поля автора действия и метки времени, чтобы определить, кто и когда обращался к файлу.

Аудит изменений конфигурации

Для organization_settings_update поле key определяет, какая настройка изменилась. Оба способа могут включать old_value и new_value; API скрывает учётные данные в настройках вебхука, описанных в разделе Конфиденциальность и безопасность данных.

Фильтруйте сохранённые данные вебхука по user_email в собственной системе анализа, чтобы отслеживать, какие администраторы вносили изменения. API аудита не поддерживает фильтр по электронной почте пользователя.

Рекомендации

Реализация конечной точки вебхука

• Отвечайте своевременно: подтверждайте получение в течение 1 секунды.
• Обрабатывайте асинхронно: помещайте полученные события в очередь на обработку.
• Проверяйте полезные нагрузки: проверяйте структуру и содержимое перед загрузкой в систему.
• Защитите конечную точку: используйте HTTPS и проверяйте настроенное значение для аутентификации.
• Отслеживайте сбои: записывайте ошибки на принимающей стороне и расследуйте пропуски доставки.

Хранение и анализ собранных журналов

• Определите политику хранения: храните собранные журналы в течение срока, необходимого вашей организации.
• Индексируйте нужные поля: используйте для анализа тип события, автора действия, метку времени и поля сеанса.
• Сопоставляйте действия: используйте session_id, чтобы связывать относящиеся друг к другу события.
• Отслеживайте закономерности: расследуйте необычные случаи доступа или административные изменения.
• Храните резервные копии: сохраняйте копии согласно политикам безопасности и конфиденциальности вашей организации.

Устранение неполадок

Проблема	Возможная причина	Следующий шаг
События вебхука не поступают	Настройка ведения журнала или конечной точки может быть не завершена	Проверьте, что ведение журнала включено и конечная точка HTTPS сохранена
Конечная точка возвращает HTTP 4xx или 5xx	Принимающая конечная точка отклонила запрос или столкнулась с ошибкой	Проверьте журналы получателя и настроенное значение аутентификации
После сбоя доставки отсутствуют события	Неудачные доставки не повторяются автоматически	Отслеживайте ошибки на стороне получателя; не полагайтесь на автоматическую повторную доставку
Раздел ключей API отсутствует	Нет необходимого разрешения	Проверьте оба разрешения
Кнопка создания ключа недоступна	Ведение журнала аудита выключено	Включите ведение журнала аудита
Кнопка создания ключа недоступна	Создание ключей API для организации не включено	Обратитесь к команде по работе с вашим аккаунтом
API не возвращает подходящих событий	Период или фильтр типа события исключает события	Проверьте даты и event_type
API возвращает 429	Ключи используют общий лимит частоты запросов организации	Соблюдайте Retry-After

Таблица 11. Устранение неполадок.

Коды ответов и рекомендации по сбору событий см. в документации API аудита. При обращении в поддержку укажите точную ошибку, время запроса к API или затронутого события вебхука либо сбоя доставки, часовой пояс и уже выполненные действия. Не включайте ключи, токены, значения аутентификации (в том числе полные заголовки авторизации) и конфиденциальное содержимое событий.

Часто задаваемые вопросы

Можно ли использовать журналы аудита, если в организации меньше 50 мест?

Да. Организация, в которой менее 50 мест, может получить доступ к журналам аудита, если хотя бы одно место использует план Enterprise Max. Условия доступа см. в статье Что такое Enterprise Max?.

Что делать, если журналы аудита были включены по ошибке и появилось неожиданное списание?

Обратитесь к команде по работе с вашим аккаунтом или через Справка > Связаться со службой поддержки, чтобы проверить списание и возможность возврата средств. См. статью Возврат средств; отключение журналов аудита не гарантирует отмену списания.

Дополнительные материалы

• API аудита
• Роли и разрешения Enterprise
• Что такое Enterprise Max?
• Хранение данных и конфиденциальность для Enterprise
• Хранение данных для корпоративных клиентов

Нужна дополнительная помощь?

Обратитесь к команде по работе с вашим аккаунтом или свяжитесь с нами через Справка > Связаться со службой поддержки. Документацию по безопасности и соответствию требованиям можно найти в Центре доверия.