API de 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"
}

Utilitzeu una Custom Push Source quan un sistema envia registres a Living Security en lloc de ser consultat per un connector del Catalog. L’emissor pot enviar matrius JSON o fitxers CSV a un endpoint HTTPS regional.

Abans de començar

Necessiteu:

permís per gestionar integracions i claus d’accés a Living Security
un emissor del costat del servidor que pugui fer sol·licituds HTTPS POST
la regió de Living Security de la vostra organització
un nom de font estable i almenys un nom de flux

Els noms de font i de flux són claus d’encaminament permanents. Els noms de font han de tenir entre 1 i 64 caràcters, i han de ser lletres minúscules, dígits o guions. Els noms de flux també admeten guions baixos. Tots dos han de començar amb una lletra o un dígit.

Tracteu la clau d’accés d’API com un secret. No la poseu en codi del navegador, no la pengeu al control de versions ni l’envieu en un tiquet de suport.

1. Registreu la font i els fluxos

Obriu Custom Push Source

Aneu a Settings → Integrations → Catalog, cerqueu Custom Push Source i seleccioneu Add.

Poseu nom a la font

Introduïu la clau d’encaminament de la font i una descripció opcional. Per exemple, utilitzeu custom-phishing-sim en lloc d’un nom visible amb espais.

Afegiu fluxos

Afegiu cada flux que utilitzarà l’emissor. El parell format per la font i el flux ha d’existir abans del primer enviament; un parell desconegut retorna 404 Not Found.

Deseu la font

Un cop creada, obriu la font a Settings → Integrations → Connected. La seva vista Push via API mostra el patró de l’endpoint i les execucions recents.

2. Creeu una clau push-ingest

Aneu a Settings → Access Keys, seleccioneu Create Access Key i trieu l’àmbit Push Ingest. Copieu immediatament el valor generat; només es mostra una vegada. La clau està vinculada a una sola organització de Living Security. La sol·licitud d’enviament no necessita cap capçalera d’organització. Consulteu API Access Keys per a la rotació i la revocació.

3. Trieu l’endpoint regional

Utilitzeu el nom d’amfitrió de l’organització de Living Security:

Regió	URL base
Estats Units	`https://api.us-east-1.livingsecurity.ai/api/v1`
Unió Europea	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Afegiu-hi /push-ingest/{integrationKey}/{streamName}. La ruta distingeix majúscules i minúscules i ha de coincidir exactament amb la font i el flux registrats.

string

requerit

El nom de la font registrada. Utilitzeu entre 1 i 64 lletres minúscules, dígits o guions, començant amb una lletra o un dígit.

string

requerit

El nom del flux registrat. S’apliquen les mateixes regles i també s’admeten els guions baixos.

string

requerit

Envieu la clau d’accés push-ingest com a Bearer <access-key>.

string

Utilitzeu application/json per a JSON o text/csv per a CSV. El servidor també pot detectar una matriu JSON quan s’omet aquesta capçalera.

string

UUID d’organització opcional. La clau d’accés ja determina l’organització. Si envieu aquesta capçalera, ha de coincidir amb l’organització de la clau; no permet seleccionar una altra organització.

Cos de la sol·licitud

Envieu una matriu JSON de nivell superior no buida d’objectes o els bytes d’un fitxer CSV amb una fila de capçalera. No hi ha cap camp contenidor JSON amb nom. Cada lot pot contenir fins a 10,000 registres i 10 MB.

4. Envieu un lot JSON

Envieu una matriu JSON no buida els elements de la qual siguin objectes. Content-Type: application/json és recomanable i molts productes emissors l’exigeixen, tot i que Living Security pot detectar un cos de tipus matriu sense aquesta capçalera.

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 sol·licitud correcta retorna 202 Accepted. La pestanya d’error mostra un 400 Bad Request quan el cos JSON està mal format:

{
  "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’acceptació vol dir que el lot s’ha emmagatzemat per al seu processament asíncron. No vol dir que tots els registres ja s’hagin interpretat com a activitat. Per a l’exemple de 400, corregiu el JSON o envieu CSV amb Content-Type: text/csv i torneu-ho a provar.

string

requerit

L’identificador d’execució d’aquest lot acceptat. Conserveu-lo per consultar l’estat del processament.

number

requerit

El nombre de registres acceptats i emmagatzemats.

string

requerit

El nom de la font utilitzada en aquest enviament.

string

requerit

El nom del flux utilitzat en aquest enviament.

Envieu CSV en lloc de JSON

Definiu Content-Type: text/csv i envieu els bytes del fitxer, tal com es mostra a l’exemple de sol·licitud CSV file anterior. La primera fila proporciona els noms dels camps. El text booleà es converteix en un booleà i el text numèric ordinari es converteix en un número. Els valors amb zeros a l’esquerra, els enters grans no segurs, les dates i la resta de text romanen com a cadenes. Les cel·les buides ometen aquest camp. Es rebutgen les files mal formades, les cometes no equilibrades i els fitxers UTF-16.

Límits de les sol·licituds i reintents

Contracte	Valor actual
Màxim de registres	10,000 per sol·licitud
Mida màxima del cos de la sol·licitud	10 MB
Taxa de sol·licituds per organització	600 sol·licituds cada 60 segons

Dividiu les exportacions més grans en lots que compleixin els dos límits. Espereu cada resposta i conserveu el runId retornat als registres de l’emissor.

Resposta	Significat	Acció de l’emissor
`202`	Lot acceptat	Registreu el `runId`; no el torneu a enviar immediatament
`400`	Nom, JSON, CSV, nombre de registres o cos no vàlids	Corregiu la sol·licitud; no la reintenteu sense canvis
`401`	Clau absent, caducada, revocada o no vàlida	Substituïu la clau i utilitzeu la capçalera Bearer
`403`	La clau no té l’àmbit necessari	Creeu una clau amb l’àmbit Push Ingest
`404`	La font o el flux no estan registrats	Registreu el parell exacte o corregiu l’URL
`413`	El cos de la sol·licitud supera els 10 MB	Dividiu el lot en sol·licituds més petites
`429`	Limitació temporal a nivell d’IP	Respecteu `Retry-After` si hi és present i espereu abans de reintentar
`503`	El compartiment de taxa de l’organització o el limitador no estan disponibles	Espereu `Retry-After` i torneu a enviar el mateix lot

El límit normal de l’organització autenticada retorna 503, no 429, de manera que els emissors de webhooks el tracten com a reintentable. Un 503 es retorna abans que s’emmagatzemi el lot; tornar a enviar el mateix lot després de l’interval indicat no duplica una execució acceptada.

Verifiqueu el flux de dades

Obriu la Custom Push Source i reviseu Push History. Confirmeu el flux, el nombre de registres, l’atribució de la clau i l’estat del processament. Les dades amb un intèrpret mantingut poden convertir-se després en persones i activitat normalitzada. Les dades sense intèrpret romanen emmagatzemades, però no generen activitat.

Utilitzeu els noms de camp exactes i l’estructura de la càrrega útil de la guia específica del proveïdor quan n’hi hagi una. Un 202 correcte demostra el lliurament, no que un esquema arbitrari s’assigni a l’activitat de Living Security.

Llista de comprovació per a la resolució de problemes

Copieu l’endpoint de la font correcta i substituïu el marcador de posició del flux.
Envieu la clau d’accés com a Authorization: Bearer …; x-api-key no s’accepta.
Confirmeu que el cos és una matriu JSON de nivell superior, no un sol objecte ni un contenidor al voltant dels registres.
Confirmeu l’ortografia de la font i del flux, incloent-hi guions, guions baixos i majúscules o minúscules.
Reviseu Push History abans de tornar a enviar un lot la resposta del qual s’hagi perdut.
Quan contacteu amb Living Security Support, inclogueu l’organització, la font, el flux, l’hora de la sol·licitud, runId si està disponible i l’estat de la resposta. No inclogueu la clau d’accés ni la càrrega útil de l’esdeveniment.

Relacionat

Zscaler ZIA Cloud NSS

Configureu un feed de registres web de Zscaler compatible amb la font, el flux, les capçaleres i l’estructura JSON exactes.

API Access Keys

Creeu, roteu i reviqueu credencials d’àmbit restringit.

Signal Data Sources

Conegueu com l’activitat interpretada de les integracions dona suport als Signals.

Integrations

Configuració de la integració

Catàleg

Canals de sortida

Abans de començar

1. Registreu la font i els fluxos

2. Creeu una clau push-ingest

3. Trieu l’endpoint regional

Cos de la sol·licitud

4. Envieu un lot JSON

Envieu CSV en lloc de JSON

Límits de les sol·licituds i reintents

Verifiqueu el flux de dades

Llista de comprovació per a la resolució de problemes

Relacionat

Zscaler ZIA Cloud NSS

API Access Keys

Signal Data Sources

Integrations

Configuració de la integració

Catàleg

Canals de sortida

​Abans de començar

​1. Registreu la font i els fluxos

​2. Creeu una clau push-ingest

​3. Trieu l’endpoint regional

​Cos de la sol·licitud

​4. Envieu un lot JSON

​Envieu CSV en lloc de JSON

​Límits de les sol·licituds i reintents

​Verifiqueu el flux de dades

​Llista de comprovació per a la resolució de problemes

​Relacionat

Zscaler ZIA Cloud NSS

API Access Keys

Signal Data Sources

Abans de començar

1. Registreu la font i els fluxos

2. Creeu una clau push-ingest

3. Trieu l’endpoint regional

Cos de la sol·licitud

4. Envieu un lot JSON

Envieu CSV en lloc de JSON

Límits de les sol·licituds i reintents

Verifiqueu el flux de dades

Llista de comprovació per a la resolució de problemes

Relacionat