> ## 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 Custom Push Source > Registrare una sorgente e inviare batch di eventi JSON o CSV a Living Security con una chiave di accesso API con ambito limitato. Utilizzare una Custom Push Source quando un sistema invia record a Living Security invece di essere interrogato da un connettore del Catalogo. Il mittente può inviare array JSON o file CSV a un endpoint HTTPS regionale. ## Prima di iniziare Sono necessari: * l'autorizzazione a gestire le integrazioni e le chiavi di accesso in Living Security * un mittente lato server in grado di eseguire richieste HTTPS `POST` * la regione di Living Security della propria organizzazione * un nome di sorgente stabile e almeno un nome di stream I nomi delle sorgenti e degli stream sono chiavi di instradamento permanenti. I nomi delle sorgenti devono essere composti da 1–64 lettere minuscole, cifre o trattini. I nomi degli stream consentono anche i caratteri di sottolineatura. Entrambi devono iniziare con una lettera o una cifra. Trattare la chiave di accesso API come un segreto. Non inserirla nel codice del browser, non includerla nel controllo del codice sorgente e non inviarla in un ticket di supporto. ## 1. Registrare la sorgente e gli stream Andare a **Impostazioni → Integrazioni → Catalogo**, individuare **Custom Push Source** e selezionare **Aggiungi**. Inserire la chiave di instradamento della sorgente e una descrizione facoltativa. Ad esempio, utilizzare `custom-phishing-sim` anziché un nome visualizzato con spazi. Aggiungere ogni stream che il mittente utilizzerà. La coppia sorgente-stream deve esistere prima del primo invio; una coppia sconosciuta restituisce `404 Not Found`. Dopo la creazione, aprire la sorgente in **Impostazioni → Integrazioni → Connesso**. La vista **Push via API** mostra il modello dell'endpoint e le esecuzioni recenti. ## 2. Creare una chiave push-ingest Andare a **Impostazioni → Access Keys**, selezionare **Create Access Key** e scegliere l'ambito **Push Ingest**. Copiare subito il valore generato: viene mostrato una sola volta. La chiave è associata a una sola organizzazione di Living Security. La richiesta di push non richiede un'intestazione relativa all'organizzazione. Per la rotazione e la revoca, consultare [Chiavi di accesso API](/it/features/settings/api-keys). ## 3. Scegliere l'endpoint regionale Utilizzare il nome host corrispondente all'organizzazione di Living Security: | Regione | URL di base | | - | - | | Stati Uniti | `https://api.us-east-1.livingsecurity.ai/api/v1` | | Unione Europea | `https://api.eu-west-1.livingsecurity.ai/api/v1` | Aggiungere `/push-ingest/{integrationKey}/{streamName}`. Il percorso distingue tra maiuscole e minuscole e deve corrispondere esattamente alla sorgente e allo stream registrati. Il nome della sorgente registrata. Utilizzare 1–64 lettere minuscole, cifre o trattini, iniziando con una lettera o una cifra. Il nome dello stream registrato. Si applicano le stesse regole; sono consentiti anche i caratteri di sottolineatura. Inviare la chiave di accesso push-ingest come `Bearer `. Utilizzare `application/json` per JSON o `text/csv` per CSV. Il server può inoltre rilevare un array JSON quando questa intestazione viene omessa. UUID dell'organizzazione facoltativo. La chiave di accesso determina già l'organizzazione. Se si invia questa intestazione, deve corrispondere all'organizzazione della chiave; non consente di selezionare un'altra organizzazione. ### Corpo della richiesta Inviare un array JSON di primo livello, non vuoto, di oggetti oppure i byte di un file CSV con una riga di intestazione. Non esiste alcun campo wrapper JSON denominato. Ogni batch può contenere fino a 10.000 record e 10 MB. ## 4. Inviare un batch JSON Inviare un array JSON non vuoto i cui elementi sono oggetti. `Content-Type: application/json` è consigliato ed è richiesto da molti prodotti di invio, anche se Living Security è in grado di rilevare un corpo di tipo array senza di esso. ```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' ``` Una richiesta riuscita restituisce `202 Accepted`. La scheda degli errori mostra un `400 Bad Request` quando il corpo JSON non è ben formato: ```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" } ``` L'accettazione significa che il batch è stato archiviato per l'elaborazione asincrona. Non significa che ogni record sia già stato interpretato in attività. Per l'esempio `400`, correggere il JSON oppure inviare un CSV con `Content-Type: text/csv`, quindi riprovare. L'ID di esecuzione per questo batch accettato. Conservarlo per verificare lo stato dell'elaborazione. Il numero di record accettati e archiviati. Il nome della sorgente utilizzato per questo push. Il nome dello stream utilizzato per questo push. ## Inviare invece un CSV Impostare `Content-Type: text/csv` e inviare i byte del file, come mostrato nell'esempio di richiesta **CSV file** riportato sopra. La prima riga fornisce i nomi dei campi. Il testo booleano diventa un valore booleano e il testo numerico ordinario diventa un numero. I valori con zeri iniziali, gli interi grandi non sicuri, le date e altro testo rimangono stringhe. Le celle vuote omettono il relativo campo. Le righe non valide, le virgolette non bilanciate e i file UTF-16 vengono rifiutati. ## Limiti delle richieste e nuovi tentativi | Contratto | Valore attuale | | - | - | | Numero massimo di record | 10.000 per richiesta | | Dimensione massima del corpo della richiesta | 10 MB | | Frequenza di richieste per organizzazione | 600 richieste ogni 60 secondi | Suddividere le esportazioni di dimensioni maggiori in batch che rispettino entrambi i limiti. Attendere ogni risposta e conservare il valore `runId` restituito nei log del mittente. | Risposta | Significato | Azione del mittente | | - | - | - | | `202` | Batch accettato | Registrare `runId`; non rinviare immediatamente | | `400` | Nome, JSON, CSV, numero di record o corpo non validi | Correggere la richiesta; non riprovare senza modifiche | | `401` | Chiave mancante, scaduta, revocata o non valida | Sostituire la chiave e utilizzare l'intestazione Bearer | | `403` | La chiave non dispone dell'ambito richiesto | Creare una chiave con ambito **Push Ingest** | | `404` | La sorgente o lo stream non sono registrati | Registrare la coppia esatta o correggere l'URL | | `413` | Il corpo della richiesta supera 10 MB | Suddividere il batch in richieste più piccole | | `429` | Limitazione temporanea a livello di IP | Rispettare `Retry-After` se presente e ridurre la frequenza | | `503` | Bucket di frequenza dell'organizzazione o limitatore non disponibile | Attendere `Retry-After`, quindi rinviare lo stesso batch | Il normale limite dell'organizzazione autenticata restituisce `503`, non `429`, pertanto i mittenti di webhook lo trattano come ritentabile. Un `503` viene restituito prima che il batch venga archiviato; rinviare lo stesso batch dopo l'intervallo indicato non duplica un'esecuzione accettata. ## Verificare il flusso di dati Aprire la Custom Push Source ed esaminare **Push History**. Verificare lo stream, il numero di record, l'attribuzione della chiave e lo stato di elaborazione. I dati con un interprete mantenuto possono quindi diventare persone e attività normalizzate. I dati senza un interprete rimangono archiviati ma non generano attività. Utilizzare i nomi esatti dei campi e la struttura del payload indicati nella guida specifica del provider, se disponibile. Un `202` riuscito dimostra la consegna, non che uno schema arbitrario corrisponda all'attività di Living Security. ## Checklist di risoluzione dei problemi * Copiare l'endpoint dalla sorgente corretta e sostituire il segnaposto dello stream. * Inviare la chiave di accesso come `Authorization: Bearer …`; `x-api-key` non è accettato. * Verificare che il corpo sia un array JSON di primo livello, non un singolo oggetto né un involucro attorno ai record. * Verificare l'ortografia della sorgente e dello stream, inclusi trattini, caratteri di sottolineatura e maiuscole/minuscole. * Esaminare **Push History** prima di rinviare un batch la cui risposta è andata persa. * Quando si contatta il [supporto di Living Security](mailto:support@livingsecurity.com), includere l'organizzazione, la sorgente, lo stream, l'ora della richiesta, `runId` se disponibile e lo stato della risposta. Non includere la chiave di accesso né il payload degli eventi. ## Argomenti correlati Configurare un feed di log web Zscaler supportato con la sorgente, lo stream, le intestazioni e la struttura JSON esatti. Creare, ruotare e revocare credenziali con ambito limitato. Scoprire come l'attività interpretata delle integrazioni supporta i segnali. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.