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

Use uma Custom Push Source quando um sistema envia registros para a Living Security, em vez de ser consultado periodicamente por um conector do Catálogo. O remetente pode enviar arrays JSON ou arquivos CSV para um endpoint HTTPS regional.

Antes de começar

Você precisa de:

permissão para gerenciar integrações e chaves de acesso na Living Security
um remetente no lado do servidor capaz de fazer requisições HTTPS POST
a região da Living Security da sua organização
um nome de origem estável e pelo menos um nome de stream

Os nomes de origem e de stream são chaves de roteamento permanentes. Os nomes de origem devem ter de 1 a 64 letras minúsculas, dígitos ou hifens. Os nomes de stream também permitem sublinhados. Ambos devem começar com uma letra ou um dígito.

Trate a chave de acesso da API como um segredo. Não a coloque em código de navegador, não a inclua em um controle de versão nem a envie em um chamado de suporte.

1. Registrar a origem e os streams

Abra a Custom Push Source

Acesse Configurações → Integrações → Catálogo, localize Custom Push Source e selecione Adicionar.

Dê um nome à origem

Informe a chave de roteamento da origem e uma descrição opcional. Por exemplo, use custom-phishing-sim em vez de um nome de exibição com espaços.

Adicione os streams

Adicione cada stream que o remetente utilizará. O par formado pela origem e pelo stream deve existir antes do primeiro envio; um par desconhecido retorna 404 Not Found.

Salve a origem

Após a criação, abra a origem em Configurações → Integrações → conectado. A visualização Push via API mostra o padrão do endpoint e as execuções recentes.

2. Criar uma chave de ingestão por push

Acesse Configurações → Access Keys, selecione Create Access Key e escolha o escopo Push Ingest. Copie o valor gerado imediatamente; ele é exibido apenas uma vez. A chave está vinculada a uma única organização da Living Security. A requisição de push não precisa de um cabeçalho de organização. Consulte Chaves de acesso de API para informações sobre rotação e revogação.

3. Escolher o endpoint regional

Use o nome de host correspondente à organização da Living Security:

Região	URL base
Estados Unidos	`https://api.us-east-1.livingsecurity.ai/api/v1`
União Europeia	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Acrescente /push-ingest/{integrationKey}/{streamName}. O caminho diferencia maiúsculas de minúsculas e deve corresponder exatamente à origem e ao stream registrados.

string

obrigatório

O nome da origem registrada. Use de 1 a 64 letras minúsculas, dígitos ou hifens, começando com uma letra ou um dígito.

string

obrigatório

O nome do stream registrado. As mesmas regras se aplicam, e sublinhados também são permitidos.

string

obrigatório

Envie a chave de acesso de ingestão por push como Bearer <access-key>.

string

Use application/json para JSON ou text/csv para CSV. O servidor também pode detectar um array JSON quando este cabeçalho é omitido.

string

UUID da organização (opcional). A chave de acesso já determina a organização. Se você enviar este cabeçalho, ele deve corresponder à organização da chave; ele não pode selecionar outra organização.

Corpo da requisição

Envie um array JSON de nível superior, não vazio, de objetos, ou os bytes de um arquivo CSV com uma linha de cabeçalho. Não há campo de encapsulamento JSON nomeado. Cada lote pode conter até 10.000 registros e 10 MB.

4. Enviar um lote JSON

Envie um array JSON não vazio cujos elementos sejam objetos. Content-Type: application/json é recomendado e exigido por muitos produtos de envio, embora a Living Security consiga detectar um corpo em formato de array sem ele.

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'

Uma requisição bem-sucedida retorna 202 Accepted. A guia de erro mostra um 400 Bad Request quando o corpo JSON está malformado:

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

A aceitação significa que o lote foi armazenado para processamento assíncrono. Isso não significa que todos os registros já foram interpretados como atividade. No exemplo de 400, corrija o JSON ou envie um CSV com Content-Type: text/csv e tente novamente.

string

obrigatório

O ID da execução deste lote aceito. Guarde-o para verificar o status do processamento.

number

obrigatório

O número de registros aceitos e armazenados.

string

obrigatório

O nome da origem usado neste envio.

string

obrigatório

O nome do stream usado neste envio.

Enviar CSV

Defina Content-Type: text/csv e envie os bytes do arquivo, conforme mostrado no exemplo de requisição CSV file acima. A primeira linha fornece os nomes dos campos. Texto booleano torna-se booleano e texto numérico comum torna-se número. Valores com zeros à esquerda, inteiros grandes não seguros, datas e outros textos permanecem como strings. Células vazias omitem o campo. Linhas malformadas, aspas não balanceadas e arquivos UTF-16 são rejeitados.

Limites de requisição e novas tentativas

Contrato	Valor atual
Máximo de registros	10.000 por requisição
Tamanho máximo do corpo da requisição	10 MB
Taxa de requisições por organização	600 requisições por 60 segundos

Divida exportações maiores em lotes que atendam a ambos os limites. Aguarde cada resposta e mantenha o runId retornado nos logs do remetente.

Resposta	Significado	Ação do remetente
`202`	Lote aceito	Registre o `runId`; não reenvie imediatamente
`400`	Nome, JSON, CSV, contagem de registros ou corpo inválido	Corrija a requisição; não tente novamente sem alterações
`401`	Chave ausente, expirada, revogada ou inválida	Substitua a chave e use o cabeçalho Bearer
`403`	A chave não possui o escopo necessário	Crie uma chave com o escopo Push Ingest
`404`	A origem ou o stream não está registrado	Registre o par exato ou corrija a URL
`413`	O corpo da requisição excede 10 MB	Divida o lote em requisições menores
`429`	Limitação temporária em nível de IP	Respeite `Retry-After` quando presente e reduza a frequência
`503`	Bucket de taxa da organização ou limitador indisponível	Aguarde `Retry-After` e reenvie o mesmo lote

O limite normal da organização autenticada retorna 503, e não 429, de modo que os remetentes de webhook o tratem como passível de nova tentativa. Um 503 é retornado antes de o lote ser armazenado; reenviar esse mesmo lote após o intervalo indicado não duplica uma execução aceita.

Verificar o fluxo de dados

Abra a Custom Push Source e revise o Push History. Confirme o stream, a contagem de registros, a atribuição da chave e o status do processamento. Os dados com um interpretador mantido podem então se tornar pessoas e atividade normalizada. Os dados sem interpretador permanecem armazenados, mas não geram atividade.

Use os nomes de campo exatos e o formato de payload do guia específico do provedor, quando houver um. Um 202 bem-sucedido comprova a entrega, mas não que um esquema arbitrário seja mapeado para a atividade da Living Security.

Lista de verificação para solução de problemas

Copie o endpoint da origem correta e substitua o marcador de posição do stream.
Envie a chave de acesso como Authorization: Bearer …; x-api-key não é aceito.
Confirme que o corpo é um array JSON de nível superior, e não um objeto único nem um envelope em torno dos registros.
Confirme a grafia da origem e do stream, incluindo hifens, sublinhados e maiúsculas e minúsculas.
Revise o Push History antes de reenviar um lote cuja resposta foi perdida.
Ao entrar em contato com o Suporte da Living Security, inclua a organização, a origem, o stream, o horário da requisição, o runId quando disponível e o status da resposta. Não inclua a chave de acesso nem o payload do evento.

Relacionados

Zscaler ZIA Cloud NSS

Configure um feed de logs web do Zscaler compatível com a origem, o stream, os cabeçalhos e o formato JSON exatos.

Chaves de acesso de API

Crie, faça a rotação e revogue credenciais com escopo definido.

Fontes de dados de Sinais

Saiba como a atividade de integração interpretada dá suporte aos Sinais.

Integrações

Configuração de integração

Catálogo

Canais de saída

Antes de começar

1. Registrar a origem e os streams

2. Criar uma chave de ingestão por push

3. Escolher o endpoint regional

Corpo da requisição

4. Enviar um lote JSON

Enviar CSV

Limites de requisição e novas tentativas

Verificar o fluxo de dados

Lista de verificação para solução de problemas

Relacionados

Zscaler ZIA Cloud NSS

Chaves de acesso de API

Fontes de dados de Sinais

Integrações

Configuração de integração

Catálogo

Canais de saída

​Antes de começar

​1. Registrar a origem e os streams

​2. Criar uma chave de ingestão por push

​3. Escolher o endpoint regional

​Corpo da requisição

​4. Enviar um lote JSON

​Enviar CSV

​Limites de requisição e novas tentativas

​Verificar o fluxo de dados

​Lista de verificação para solução de problemas

​Relacionados

Zscaler ZIA Cloud NSS

Chaves de acesso de API

Fontes de dados de Sinais

Antes de começar

1. Registrar a origem e os streams

2. Criar uma chave de ingestão por push

3. Escolher o endpoint regional

Corpo da requisição

4. Enviar um lote JSON

Enviar CSV

Limites de requisição e novas tentativas

Verificar o fluxo de dados

Lista de verificação para solução de problemas

Relacionados