API Custom Push Source

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: text/csv' \
  --data-binary '@events.csv'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

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

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: text/csv' \
  --data-binary '@events.csv'

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

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

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

Aprire Custom Push Source

Andare a Impostazioni → Integrazioni → Catalogo, individuare Custom Push Source e selezionare Aggiungi.

Assegnare un nome alla sorgente

Inserire la chiave di instradamento della sorgente e una descrizione facoltativa. Ad esempio, utilizzare custom-phishing-sim anziché un nome visualizzato con spazi.

Aggiungere gli stream

Aggiungere ogni stream che il mittente utilizzerà. La coppia sorgente-stream deve esistere prima del primo invio; una coppia sconosciuta restituisce 404 Not Found.

Salvare la sorgente

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.

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.

string

obbligatorio

Il nome della sorgente registrata. Utilizzare 1–64 lettere minuscole, cifre o trattini, iniziando con una lettera o una cifra.

string

obbligatorio

Il nome dello stream registrato. Si applicano le stesse regole; sono consentiti anche i caratteri di sottolineatura.

string

obbligatorio

Inviare la chiave di accesso push-ingest come Bearer <access-key>.

string

Utilizzare application/json per JSON o text/csv per CSV. Il server può inoltre rilevare un array JSON quando questa intestazione viene omessa.

string

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.

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "email": "person@example.com",
      "event_at": "2026-09-21T14:30:00Z",
      "action": "reported"
    }
  ]'

curl --request POST \
  'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
  --header 'Authorization: Bearer <access-key>' \
  --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:

{
  "runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
  "recordsAccepted": 1,
  "integrationKey": "custom-phishing-sim",
  "streamName": "events"
}

{
  "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.

string

obbligatorio

L’ID di esecuzione per questo batch accettato. Conservarlo per verificare lo stato dell’elaborazione.

number

obbligatorio

Il numero di record accettati e archiviati.

string

obbligatorio

Il nome della sorgente utilizzato per questo push.

string

obbligatorio

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, 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

Zscaler ZIA Cloud NSS

Configurare un feed di log web Zscaler supportato con la sorgente, lo stream, le intestazioni e la struttura JSON esatti.

Chiavi di accesso API

Creare, ruotare e revocare credenziali con ambito limitato.

Origini dati dei Segnali

Scoprire come l’attività interpretata delle integrazioni supporta i segnali.

Integrazioni

Configurazione delle integrazioni

Catalogo

Canali in uscita

Prima di iniziare

1. Registrare la sorgente e gli stream

2. Creare una chiave push-ingest

3. Scegliere l’endpoint regionale

Corpo della richiesta

4. Inviare un batch JSON

Inviare invece un CSV

Limiti delle richieste e nuovi tentativi

Verificare il flusso di dati

Checklist di risoluzione dei problemi

Argomenti correlati

Zscaler ZIA Cloud NSS

Chiavi di accesso API

Origini dati dei Segnali

Integrazioni

Configurazione delle integrazioni

Catalogo

Canali in uscita

​Prima di iniziare

​1. Registrare la sorgente e gli stream

​2. Creare una chiave push-ingest

​3. Scegliere l’endpoint regionale

​Corpo della richiesta

​4. Inviare un batch JSON

​Inviare invece un CSV

​Limiti delle richieste e nuovi tentativi

​Verificare il flusso di dati

​Checklist di risoluzione dei problemi

​Argomenti correlati

Zscaler ZIA Cloud NSS

Chiavi di accesso API

Origini dati dei Segnali

Prima di iniziare

1. Registrare la sorgente e gli stream

2. Creare una chiave push-ingest

3. Scegliere l’endpoint regionale

Corpo della richiesta

4. Inviare un batch JSON

Inviare invece un CSV

Limiti delle richieste e nuovi tentativi

Verificare il flusso di dati

Checklist di risoluzione dei problemi

Argomenti correlati