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

Utilice una Custom Push Source cuando un sistema envíe registros a Living Security en lugar de ser consultado periódicamente por un conector del Catálogo. El remitente puede enviar arreglos JSON o archivos CSV a un punto de conexión HTTPS regional.

Antes de comenzar

Necesita lo siguiente:

permiso para administrar integraciones y claves de acceso en Living Security
un remitente del lado del servidor que pueda realizar solicitudes HTTPS POST
la región de Living Security de su organización
un nombre de fuente estable y al menos un nombre de flujo

Los nombres de fuente y de flujo son claves de enrutamiento permanentes. Los nombres de fuente deben tener entre 1 y 64 caracteres, entre letras minúsculas, dígitos o guiones. Los nombres de flujo también admiten guiones bajos. Ambos deben comenzar con una letra o un dígito.

Trate la clave de acceso de API como un secreto. No la coloque en código del navegador, no la confirme en el control de código fuente ni la envíe en un tique de soporte.

1. Registre la fuente y los flujos

Abra Custom Push Source

Vaya a Configuración → Integraciones → Catálogo, busque Custom Push Source y seleccione Agregar.

Asigne un nombre a la fuente

Introduzca la clave de enrutamiento de la fuente y una descripción opcional. Por ejemplo, utilice custom-phishing-sim en lugar de un nombre para mostrar con espacios.

Agregue flujos

Agregue cada flujo que utilizará el remitente. El par de fuente y flujo debe existir antes del primer envío; un par desconocido devuelve 404 Not Found.

Guarde la fuente

Después de crearla, abra la fuente en Configuración → Integraciones → conectado. Su vista Push via API muestra el patrón del punto de conexión y las ejecuciones recientes.

2. Cree una clave de ingesta por envío

Vaya a Configuración → Access Keys, seleccione Create Access Key y elija el alcance Push Ingest. Copie el valor generado de inmediato; solo se muestra una vez. La clave está vinculada a una sola organización de Living Security. La solicitud de envío no necesita un encabezado de organización. Consulte Claves de acceso de API para conocer la rotación y la revocación.

3. Elija el punto de conexión regional

Utilice el nombre de host correspondiente a la organización de Living Security:

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

Agregue /push-ingest/{integrationKey}/{streamName} al final. La ruta distingue entre mayúsculas y minúsculas y debe coincidir exactamente con la fuente y el flujo registrados.

string

requerido

El nombre de la fuente registrada. Utilice entre 1 y 64 letras minúsculas, dígitos o guiones, comenzando con una letra o un dígito.

string

requerido

El nombre del flujo registrado. Se aplican las mismas reglas y, además, se permiten guiones bajos.

string

requerido

Envíe la clave de acceso de ingesta por envío como Bearer <access-key>.

string

Utilice application/json para JSON o text/csv para CSV. El servidor también puede detectar un arreglo JSON cuando se omite este encabezado.

string

UUID de organización opcional. La clave de acceso ya determina la organización. Si envía este encabezado, debe coincidir con la organización de la clave; no puede seleccionar otra organización.

Cuerpo de la solicitud

Envíe un arreglo JSON de nivel superior, no vacío, de objetos, o los bytes de un archivo CSV con una fila de encabezado. No existe un campo contenedor JSON con nombre. Cada lote puede contener hasta 10,000 registros y 10 MB.

4. Envíe un lote JSON

Envíe un arreglo JSON no vacío cuyos elementos sean objetos. Se recomienda Content-Type: application/json, y muchos productos remitentes lo requieren, aunque Living Security puede detectar un cuerpo de tipo arreglo sin él.

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 solicitud correcta devuelve 202 Accepted. La pestaña de error muestra 400 Bad Request cuando el cuerpo JSON tiene un formato incorrecto:

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

La aceptación significa que el lote se almacenó para su procesamiento asíncrono. No significa que todos los registros ya se hayan interpretado como actividad. Para el ejemplo de 400, corrija el JSON o envíe un CSV con Content-Type: text/csv y vuelva a intentarlo.

string

requerido

El ID de ejecución de este lote aceptado. Consérvelo para consultar el estado del procesamiento.

number

requerido

El número de registros aceptados y almacenados.

string

requerido

El nombre de la fuente utilizada en este envío.

string

requerido

El nombre del flujo utilizado en este envío.

Envío de CSV

Establezca Content-Type: text/csv y envíe los bytes del archivo, como se muestra en el ejemplo de solicitud CSV file anterior. La primera fila proporciona los nombres de los campos. El texto booleano se convierte en un valor booleano y el texto numérico ordinario se convierte en un número. Los valores con ceros a la izquierda, los enteros grandes no seguros, las fechas y otros textos permanecen como cadenas. Las celdas vacías omiten ese campo. Se rechazan las filas con formato incorrecto, las comillas sin cerrar y los archivos UTF-16.

Límites de solicitud y reintentos

Contrato	Valor actual
Máximo de registros	10,000 por solicitud
Tamaño máximo del cuerpo de la solicitud	10 MB
Tasa de solicitudes por organización	600 solicitudes por 60 segundos

Divida las exportaciones más grandes en lotes que cumplan ambos límites. Espere cada respuesta y conserve el runId devuelto en los registros del remitente.

Respuesta	Significado	Acción del remitente
`202`	Lote aceptado	Registre el `runId`; no lo reenvíe de inmediato
`400`	Nombre, JSON, CSV, número de registros o cuerpo no válidos	Corrija la solicitud; no la reintente sin cambios
`401`	Clave ausente, vencida, revocada o no válida	Reemplace la clave y utilice el encabezado Bearer
`403`	La clave no tiene el alcance requerido	Cree una clave con el alcance Push Ingest
`404`	La fuente o el flujo no están registrados	Registre el par exacto o corrija la URL
`413`	El cuerpo de la solicitud supera los 10 MB	Divida el lote en solicitudes más pequeñas
`429`	Limitación temporal a nivel de IP	Respete `Retry-After` cuando esté presente y espere antes de reintentar
`503`	Depósito de tasa de la organización o limitador no disponible	Espere `Retry-After` y vuelva a enviar el mismo lote

El límite normal de la organización autenticada devuelve 503, no 429, por lo que los remitentes de webhooks lo tratan como reintentable. Se devuelve un 503 antes de que el lote se almacene; reenviar ese mismo lote después del intervalo indicado no duplica una ejecución aceptada.

Verifique el flujo de datos

Abra la Custom Push Source y revise Push History. Confirme el flujo, el número de registros, la atribución de la clave y el estado del procesamiento. Los datos con un intérprete mantenido pueden convertirse después en personas y actividad normalizada. Los datos sin intérprete permanecen almacenados, pero no generan actividad.

Utilice los nombres de campo exactos y la estructura de la carga útil de la guía específica del proveedor cuando exista. Un 202 correcto demuestra la entrega, no que un esquema arbitrario se asigne a la actividad de Living Security.

Lista de verificación para la solución de problemas

Copie el punto de conexión de la fuente correcta y reemplace el marcador de posición del flujo.
Envíe la clave de acceso como Authorization: Bearer …; x-api-key no se acepta.
Confirme que el cuerpo sea un arreglo JSON de nivel superior, no un único objeto ni un envoltorio alrededor de los registros.
Confirme la ortografía de la fuente y del flujo, incluidos los guiones, los guiones bajos y las mayúsculas y minúsculas.
Revise Push History antes de reenviar un lote cuya respuesta se perdió.
Al comunicarse con Soporte de Living Security, incluya la organización, la fuente, el flujo, la hora de la solicitud, el runId cuando esté disponible y el estado de la respuesta. No incluya la clave de acceso ni la carga útil del evento.

Temas relacionados

Zscaler ZIA Cloud NSS

Configure una fuente de registros web de Zscaler compatible con la fuente, el flujo, los encabezados y la estructura JSON exactos.

Claves de acceso de API

Cree, rote y revoque credenciales con alcance limitado.

Fuentes de datos de Señales

Conozca cómo la actividad interpretada de las integraciones respalda las señales.

Integraciones

Configuración de integraciones

Catálogo

Canales de salida

Antes de comenzar

1. Registre la fuente y los flujos

2. Cree una clave de ingesta por envío

3. Elija el punto de conexión regional

Cuerpo de la solicitud

4. Envíe un lote JSON

Envío de CSV

Límites de solicitud y reintentos

Verifique el flujo de datos

Lista de verificación para la solución de problemas

Temas relacionados

Zscaler ZIA Cloud NSS

Claves de acceso de API

Fuentes de datos de Señales

Integraciones

Configuración de integraciones

Catálogo

Canales de salida

​Antes de comenzar

​1. Registre la fuente y los flujos

​2. Cree una clave de ingesta por envío

​3. Elija el punto de conexión regional

​Cuerpo de la solicitud

​4. Envíe un lote JSON

​Envío de CSV

​Límites de solicitud y reintentos

​Verifique el flujo de datos

​Lista de verificación para la solución de problemas

​Temas relacionados

Zscaler ZIA Cloud NSS

Claves de acceso de API

Fuentes de datos de Señales

Antes de comenzar

1. Registre la fuente y los flujos

2. Cree una clave de ingesta por envío

3. Elija el punto de conexión regional

Cuerpo de la solicitud

4. Envíe un lote JSON

Envío de CSV

Límites de solicitud y reintentos

Verifique el flujo de datos

Lista de verificación para la solución de problemas

Temas relacionados