Audit Logs

Monitora le attività supportate nella tua organizzazione Enterprise con i registri di controllo consegnati tramite webhook.

​

Panoramica

I registri di controllo sono disponibili per le organizzazioni Enterprise con almeno 50 posti o con almeno un posto Enterprise Max. Gli amministratori possono usarli per esaminare le attività e monitorare le modifiche amministrative.

Puoi ricevere gli eventi registrati tramite un webhook. Il testo delle query e delle risposte è limitato ai primi 500 caratteri.

I registri di controllo non acquisiscono tutte le azioni. I registri di controllo non registrano le modifiche al livello di abbonamento dei posti effettuate tramite SCIM, che sincronizza i membri con il provider di identità, o tramite strumenti per operazioni in blocco. Sono escluse anche le aggiunte e le rimozioni di membri effettuate con operazioni in blocco tramite CSV.

​

Prima di iniziare

• Verifica che l’organizzazione soddisfi il requisito relativo ai posti indicato sopra.
• Chiedi a un amministratore con accesso alle impostazioni dell’organizzazione di abilitare la registrazione.
• Per la consegna tramite webhook, prepara un endpoint HTTPS e un valore di autenticazione.

​

Privacy e sicurezza dei dati

I payload dei webhook possono contenere informazioni personali e contenuti registrati, non solo identificatori delle attività. A seconda dell’evento, i metadati possono includere il testo delle query e delle risposte, i nomi dei file, gli indirizzi email dei membri interessati, i valori delle impostazioni dell’organizzazione e i dettagli delle attività di Perplexity Computer.

Limita l’accesso ai registri raccolti secondo le politiche sulla privacy della tua organizzazione. Mantieni riservati gli URL dei webhook e i valori di autenticazione.

Per le pratiche relative ai dati nell’ambito di Enterprise, consulta Conservazione dei dati e privacy per Enterprise. Il Centro di fiducia fornisce documentazione sulla sicurezza e sulla conformità, mentre l’Addendum sul trattamento dei dati definisce i termini contrattuali per il trattamento dei dati quando è incorporato nel tuo accordo.

​

Abilita i registri di controllo

1. Vai a Impostazioni dell’organizzazione.

2. Apri Dati e privacy.

3. In Impostazioni registro di controllo, attiva Abilita registrazione di controllo.

   

   Figura 1: Il comando per abilitare la registrazione nelle impostazioni dei registri di controllo.

Per la consegna tramite webhook, completa questi passaggi:

1. Inserisci il tuo endpoint HTTPS in URL Webhook.

   

   Figura 2: Impostazioni dell’URL del webhook e dell’intestazione di autorizzazione.

2. Fai clic su Salva accanto a URL Webhook.

3. Se l’endpoint richiede l’autenticazione, inserisci il valore nel campo dell’intestazione di autorizzazione.

4. Fai clic su Salva accanto al campo dell’intestazione di autorizzazione.

Se non specifichi uno schema di autorizzazione, il valore inserito viene inviato come token Bearer. Consulta Autenticazione del webhook per i due formati supportati.

​

Come verificare il risultato

Dopo un’azione supportata, verifica che l’endpoint ricevente riceva un evento webhook e restituisca una risposta HTTP 2xx.

​

Autenticazione del webhook

Puoi proteggere l’endpoint webhook con un token Bearer o un valore di autorizzazione completo. Configura il valore previsto dall’endpoint ricevente.

​

Token Bearer

Fornisci un token senza prefisso, ad esempio YOUR_WEBHOOK_TOKEN. Perplexity antepone Bearer e invia Authorization: Bearer YOUR_WEBHOOK_TOKEN.

​

Intestazione di autorizzazione personalizzata

Fornisci un valore di autorizzazione completo che includa il relativo schema. Ad esempio, Splunk YOUR_HEC_TOKEN viene inviato come Authorization: Splunk YOUR_HEC_TOKEN.

​

Consegna tramite webhook

​

Formato delle richieste

I registri di controllo vengono consegnati all’URL del webhook tramite richieste HTTP POST. Il corpo della richiesta usa application/json.

​

Intestazione di autenticazione

Se hai configurato un valore di autenticazione, Perplexity lo include nell’intestazione Authorization. Consulta Autenticazione del webhook per i formati Bearer e con schema personalizzato.

​

Gestione delle risposte

L’endpoint webhook deve restituire una risposta HTTP 2xx per confermare la ricezione entro 1 secondo. Perplexity registra gli errori di consegna, comprese le risposte HTTP 4xx e 5xx, ma non riprova automaticamente le consegne non riuscite o scadute. Monitora l’endpoint ricevente per individuare errori ed eventi mancanti.

​

Schema dei registri di controllo del webhook

Gli eventi del webhook usano i campi seguenti.

Campo	Tipo	Obbligatorio	Descrizione
uuid	Stringa	Sì	Identificatore dell’evento
timestamp	Stringa	Sì	Timestamp RFC 3339
event_type	Stringa	Sì	Tipo di evento
user_email	Stringa	Sì	Email del membro che ha eseguito l’azione
ip_address	Stringa	Sì	Indirizzo del client o indicatore non IP
user_agent	Stringa	Sì	User agent del client
session_id	Stringa o null	No	Identificatore degli eventi correlati
user_id	Stringa o null	No	Identificatore dell’utente, se registrato
metadata	Oggetto o null	No	Dati specifici dell’evento

Tabella 1: Campi del payload del webhook.

Un campo stringa obbligatorio può essere vuoto quando non viene registrato un valore. Non presumere che ogni valore di ip_address sia un indirizzo IP.

​

Tipi di eventi

Le tabelle seguenti descrivono i tipi di eventi del webhook documentati, senza garantire che ogni azione venga registrata.

​

Eventi di attività degli utenti

Tipo di evento	Descrizione
login	Accesso riuscito
query	Query di ricerca inviata
answer_generated	Risposta restituita
file_upload	File caricato in una query o in un progetto
file_download	File scaricato da un progetto
file_delete	File eliminato da una query o da un progetto

Tabella 2: Eventi di attività degli utenti.

Gli eventi delle query possono includere metadata.attachments, con file_uuid e file_name per ciascun file allegato.

​

Eventi dei thread

Tipo di evento	Descrizione
thread_forked	Thread copiato
thread_exported	Thread esportato
thread_shared	Thread condiviso
thread_deleted	Thread eliminato

Tabella 3: Eventi dei thread.

​

Eventi relativi ai membri

Tipo di evento	Descrizione
member_invited	Membro invitato
member_invite_rescinded	Invito in sospeso revocato
member_removed	Membro rimosso
member_role_changed	Ruolo del membro modificato

Tabella 4: Eventi relativi ai membri.

​

Eventi dell’organizzazione

Tipo di evento	Descrizione
organization_settings_update	Impostazione dell’organizzazione modificata

Tabella 5: Eventi dell’organizzazione.

​

Eventi di ruoli e gruppi

Tipo di evento	Descrizione
role_created	Ruolo personalizzato creato
role_updated	Dettagli o autorizzazioni del ruolo aggiornati
role_deleted	Ruolo personalizzato eliminato
role_users_changed	Utenti aggiunti a un ruolo o rimossi da un ruolo
role_groups_changed	Gruppi aggiunti a un ruolo o rimossi da un ruolo
group_created	Gruppo di utenti creato
group_deleted	Gruppo di utenti eliminato
group_members_changed	Composizione del gruppo modificata

Tabella 6: Eventi di ruoli e gruppi.

Per role_users_changed e role_groups_changed, i metadati possono includere un valore action pari a added o removed. Usa questo campo per distinguere un’aggiunta da una rimozione.

​

Eventi dell’agente Comet

Tipo di evento	Descrizione
comet_agent_action	Azione automatizzata di Comet

Tabella 7: Eventi dell’agente Comet.

​

Eventi dei connettori

Tipo di evento	Descrizione
connector_connected	Connettore di terze parti collegato
connector_disconnected	Connettore di terze parti scollegato

Tabella 8: Eventi dei connettori.

​

Eventi di Computer

Tipo di evento	Descrizione
computer_task_started	Attività di Computer avviata
computer_agent_action	Azione automatizzata durante un’attività
computer_task_completed	Attività completata correttamente
computer_task_error	Attività non riuscita a causa di un errore

Tabella 9: Eventi di Computer.

​

Esempio di payload del webhook

Questo payload JSON illustrativo rappresenta un evento di query consegnato a un webhook generico.

{
  "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?"
  }
}

​

Formattazione specifica per piattaforma

​

Webhook di Slack

Per un URL webhook che inizia con https://hooks.slack.com, Perplexity usa il formato Block Kit di Slack. L’array blocks contiene sezioni per il tipo di evento, i dettagli del membro e del client e i metadati dell’evento, quando presenti.

Le etichette dei tipi di evento hanno le iniziali delle parole maiuscole e non contengono trattini bassi. La formattazione di Slack tronca i singoli valori dei metadati a 500 caratteri e la sezione dei metadati a 2.500 caratteri, con un avviso di troncamento per i valori lunghi.

​

Splunk HTTP Event Collector

Quando il valore di autorizzazione inizia con Splunk, Perplexity racchiude il payload in un oggetto event per HTTP Event Collector (HEC) di Splunk. Questo esempio illustrativo mostra la struttura contenitore:

{
  "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": {}
  }
}

​

Webhook generici

Per le altre destinazioni webhook, Perplexity invia il payload JSON standard senza una struttura contenitore specifica per la piattaforma. Consulta Esempio di payload del webhook per il formato.

​

Scenari comuni con i webhook

​

Monitora le sessioni di ricerca

Usa session_id per correlare una query alla relativa risposta.

1. Trova l’evento della query

   Leggi query_str nei metadati dell’evento. Annota il relativo session_id per trovare gli eventi correlati.

2. Associa l’evento della risposta

   Trova l’evento answer_generated con lo stesso session_id. Quando viene registrato, answer contiene al massimo i primi 500 caratteri della risposta, insieme al model usato.

​

Monitora l’accesso ai file

Usa gli identificatori dei file per correlare caricamenti e download. I metadati degli eventi webhook possono includere i dettagli registrati dei file e dei progetti.

1. Trova il caricamento del file

   Leggi il file_uuid dell’evento di caricamento. Annota l’identificatore per confrontarlo con gli eventi successivi.

2. Associa i download del file

   Trova gli eventi di download con lo stesso file_uuid. Usa i campi relativi all’autore dell’azione e al timestamp per vedere chi ha avuto accesso al file e quando.

​

Verifica le modifiche alla configurazione

Per organization_settings_update, il campo key dell’impostazione identifica ciò che è cambiato. I metadati del webhook possono includere old_value e new_value.

Filtra i dati del webhook archiviati per user_email nel tuo sistema di analisi per individuare gli amministratori che hanno apportato modifiche.

​

Buone pratiche

​

Implementa l’endpoint webhook

• Rispondi tempestivamente: conferma la ricezione entro 1 secondo.
• Elabora in modo asincrono: metti in coda gli eventi ricevuti per l’elaborazione.
• Convalida i payload: verifica struttura e contenuto prima dell’acquisizione.
• Proteggi l’endpoint: usa HTTPS e convalida il valore di autenticazione configurato.
• Monitora gli errori: registra gli errori sul lato ricevente ed esamina le lacune nella consegna.

​

Archivia e analizza i registri raccolti

• Definisci una politica di conservazione: conserva i registri raccolti per il periodo richiesto dalla tua organizzazione.
• Indicizza i campi pertinenti: usa i campi relativi al tipo di evento, all’autore dell’azione, al timestamp e alla sessione per l’analisi.
• Correla le attività: usa session_id per collegare gli eventi correlati.
• Monitora i comportamenti ricorrenti: esamina accessi o modifiche amministrative insoliti.
• Mantieni copie di backup: conserva le copie secondo le politiche di sicurezza e privacy della tua organizzazione.

​

Risoluzione dei problemi

Problema	Possibile causa	Passaggio successivo
Nessun evento webhook ricevuto	La configurazione della registrazione o dell’endpoint potrebbe essere incompleta	Verifica che la registrazione sia abilitata e che sia stato salvato un endpoint HTTPS
L’endpoint restituisce HTTP 4xx o 5xx	L’endpoint ricevente ha rifiutato la richiesta o ha riscontrato un errore	Controlla i log del destinatario e il valore di autenticazione configurato
Eventi mancanti dopo una consegna non riuscita	Le consegne non riuscite non vengono ritentate automaticamente	Monitora gli errori del destinatario; non fare affidamento su una ripetizione automatica

Tabella 10: Problemi comuni di consegna tramite webhook.

Quando contatti l’assistenza, includi l’errore esatto, l’ora dell’evento interessato o della consegna non riuscita, il fuso orario e i passaggi già provati. Ometti valori di autenticazione, token e contenuti sensibili degli eventi.

​

Domande frequenti

​

Posso usare i registri di controllo con meno di 50 posti?

Sì. Un’organizzazione con meno di 50 posti può accedere ai registri di controllo se almeno un posto ha il piano Enterprise Max. Consulta Cos’è Enterprise Max? per i requisiti di accesso.

​

Cosa devo fare se ho abilitato i registri di controllo per errore e vedo un addebito imprevisto?

Contatta il team che segue il tuo account o usa Aiuto > Contatta l’assistenza per esaminare l’addebito e l’eventuale diritto a un rimborso. Consulta Rimborsi; disabilitare i registri di controllo non garantisce lo storno dell’addebito.

​

Riferimenti correlati

• Ruoli e autorizzazioni Enterprise
• Cos’è Enterprise Max?
• Conservazione dei dati e privacy per Enterprise
• Conservazione dei dati per Enterprise

​

Hai bisogno di ulteriore aiuto?

Rivolgiti al team che segue il tuo account o contattaci tramite Aiuto > Contatta l’assistenza. Visita il Centro di fiducia per la documentazione sulla sicurezza e sulla conformità.