> ## 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.

# Custom Push Source API

> Registreer een bron en verstuur JSON- of CSV-eventbatches naar Living Security met een API-toegangssleutel met beperkte scope.

Gebruik een Custom Push Source wanneer een systeem records naar Living Security verstuurt in plaats van dat het door een Catalog-connector wordt bevraagd. De verzender kan JSON-arrays of CSV-bestanden indienen bij een regionaal HTTPS-endpoint.

## Voordat u begint

U hebt het volgende nodig:

* toestemming om integraties en toegangssleutels te beheren in Living Security
* een server-side verzender die HTTPS-`POST`-verzoeken kan uitvoeren
* de Living Security-regio van uw organisatie
* een stabiele bronnaam en ten minste één streamnaam

Bronnamen en streamnamen zijn permanente routeringssleutels. Bronnamen bestaan uit 1–64 kleine letters, cijfers of koppeltekens. Voor streamnamen zijn ook underscores toegestaan. Beide moeten beginnen met een letter of cijfer.

<Warning>
  Behandel de API-toegangssleutel als een geheim. Plaats deze niet in browsercode, commit deze
  niet naar broncodebeheer en verstuur deze niet in een supportticket.
</Warning>

## 1. Registreer de bron en de streams

<Steps>
  <Step title="Open Custom Push Source">
    Ga naar **Instellingen → Integraties → Catalog**, zoek **Custom Push Source** en selecteer **toevoegen**.
  </Step>

  <Step title="Geef de bron een naam">
    Voer de routeringssleutel van de bron in en eventueel een beschrijving. Gebruik bijvoorbeeld `custom-phishing-sim` in plaats van een weergavenaam met spaties.
  </Step>

  <Step title="Voeg streams toe">
    Voeg elke stream toe die de verzender gaat gebruiken. Het paar van bron en stream moet bestaan vóór de eerste push; een onbekend paar geeft `404 Not Found` terug.
  </Step>

  <Step title="Sla de bron op">
    Open de bron na het aanmaken onder **Instellingen → Integraties → Verbonden**. De weergave **Push via API** toont het endpointpatroon en recente runs.
  </Step>
</Steps>

## 2. Maak een push-ingest-sleutel aan

Ga naar **Instellingen → Access Keys**, selecteer **Create Access Key** en kies de scope **Push Ingest**. Kopieer de gegenereerde waarde direct; deze wordt slechts één keer weergegeven.

De sleutel is gekoppeld aan één Living Security-organisatie. Het push-verzoek heeft geen organisatieheader nodig. Zie [API-toegangssleutels](/nl/features/settings/api-keys) voor rotatie en intrekking.

## 3. Kies het regionale endpoint

Gebruik de hostnaam voor de Living Security-organisatie:

| Regio | Basis-URL |
| - | - |
| Verenigde Staten | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Europese Unie | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Voeg `/push-ingest/{integrationKey}/{streamName}` toe. Het pad is hoofdlettergevoelig en moet exact overeenkomen met de geregistreerde bron en stream.

<ParamField path="integrationKey" type="string" required>
  De geregistreerde bronnaam. Gebruik 1–64 kleine letters, cijfers of koppeltekens, beginnend met een letter of cijfer.
</ParamField>

<ParamField path="streamName" type="string" required>
  De geregistreerde streamnaam. Dezelfde regels zijn van toepassing, en underscores zijn ook toegestaan.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Verstuur de push-ingest-toegangssleutel als `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Gebruik `application/json` voor JSON of `text/csv` voor CSV. De server kan ook een JSON-array herkennen wanneer deze header ontbreekt.
</ParamField>

<ParamField header="x-organization-id" type="string">
  Optionele organisatie-UUID. De toegangssleutel bepaalt de organisatie al. Als u deze header meestuurt, moet deze overeenkomen met de organisatie van de sleutel; hiermee kunt u geen andere organisatie selecteren.
</ParamField>

### Request body

Verstuur een niet-lege JSON-array van objecten op het hoogste niveau, of CSV-bestandsbytes met een koptekstrij. Er is geen benoemd JSON-wrapperveld. Elke batch kan maximaal 10.000 records en 10 MB bevatten.

## 4. Verstuur een JSON-batch

Verstuur een niet-lege JSON-array waarvan de elementen objecten zijn. `Content-Type: application/json` wordt aanbevolen en is vereist door veel verzendende producten, ook al kan Living Security een array-body herkennen zonder deze header.

<RequestExample>
  ```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 <access-key>' \
    --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 <access-key>' \
    --header 'Content-Type: text/csv' \
    --data-binary '@events.csv'
  ```
</RequestExample>

Een geslaagd verzoek geeft `202 Accepted` terug. Het tabblad voor fouten toont een `400 Bad Request` wanneer de JSON-body onjuist is opgebouwd:

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>

Acceptatie betekent dat de batch is opgeslagen voor asynchrone verwerking. Dit betekent niet dat elk record al is geïnterpreteerd tot activiteit.
Corrigeer bij het voorbeeld `400` de JSON of verstuur CSV met `Content-Type: text/csv` en probeer het opnieuw.

<ResponseField name="runId" type="string" required>
  De run-ID voor deze geaccepteerde batch. Bewaar deze om de verwerkingsstatus te controleren.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Het aantal records dat is geaccepteerd en opgeslagen.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  De bronnaam die voor deze push is gebruikt.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  De streamnaam die voor deze push is gebruikt.
</ResponseField>

## In plaats daarvan CSV versturen

Stel `Content-Type: text/csv` in en verstuur de bestandsbytes, zoals getoond in het voorbeeldverzoek **CSV file** hierboven. De eerste rij bevat de veldnamen.

Booleaanse tekst wordt een boolean en gewone numerieke tekst wordt een getal. Waarden met voorloopnullen, onveilig grote gehele getallen, datums en andere tekst blijven strings. Lege cellen laten dat veld weg. Onjuist opgebouwde rijen, onevenwichtige aanhalingstekens en UTF-16-bestanden worden geweigerd.

## Verzoeklimieten en nieuwe pogingen

| Contract | Huidige waarde |
| - | - |
| Maximum aantal records | 10.000 per verzoek |
| Maximale request body | 10 MB |
| Verzoeklimiet per organisatie | 600 verzoeken per 60 seconden |

Splits grotere exports op in batches die aan beide limieten voldoen. Wacht op elke respons en bewaar de geretourneerde `runId` in de logboeken van de verzender.

| Respons | Betekenis | Actie van de verzender |
| - | - | - |
| `202` | Batch geaccepteerd | Leg de `runId` vast; verstuur niet direct opnieuw |
| `400` | Ongeldige naam, JSON, CSV, aantal records of body | Corrigeer het verzoek; probeer niet opnieuw zonder wijziging |
| `401` | Ontbrekende, verlopen, ingetrokken of ongeldige sleutel | Vervang de sleutel en gebruik de Bearer-header |
| `403` | Sleutel heeft niet de vereiste scope | Maak een sleutel aan met de scope **Push Ingest** |
| `404` | Bron of stream is niet geregistreerd | Registreer het exacte paar of corrigeer de URL |
| `413` | Request body is groter dan 10 MB | Splits de batch op in kleinere verzoeken |
| `429` | Tijdelijke throttling op IP-niveau | Houd rekening met `Retry-After` indien aanwezig en wacht langer tussen pogingen |
| `503` | Ratebucket van de organisatie of limiter niet beschikbaar | Wacht op `Retry-After` en verstuur dezelfde batch opnieuw |

De normale limiet voor geauthenticeerde organisaties geeft `503` terug en niet `429`, zodat webhook-verzenders dit als opnieuw te proberen behandelen. Een `503` wordt teruggegeven voordat de batch wordt opgeslagen; het opnieuw versturen van dezelfde batch na het aangegeven interval leidt niet tot een dubbele geaccepteerde run.

## De gegevensstroom controleren

Open de Custom Push Source en bekijk **Push History**. Controleer de stream, het aantal records, de toewijzing van de sleutel en de verwerkingsstatus. Gegevens met een onderhouden interpreter kunnen vervolgens worden omgezet in personen en genormaliseerde activiteit. Gegevens zonder interpreter blijven opgeslagen, maar leveren geen activiteit op.

<Info>
  Gebruik de exacte veldnamen en payloadstructuur uit de providerspecifieke handleiding
  wanneer die bestaat. Een geslaagde `202` bewijst de aflevering, niet dat een
  willekeurig schema wordt gekoppeld aan Living Security-activiteit.
</Info>

## Checklist voor probleemoplossing

* Kopieer het endpoint van de juiste bron en vervang de placeholder voor de stream.
* Verstuur de toegangssleutel als `Authorization: Bearer …`; `x-api-key` wordt niet geaccepteerd.
* Controleer of de body een JSON-array op het hoogste niveau is, en niet een enkel object of een envelop rondom de records.
* Controleer de spelling van bron en stream, inclusief koppeltekens, underscores en hoofdlettergebruik.
* Bekijk **Push History** voordat u een batch opnieuw verstuurt waarvan de respons verloren is gegaan.
* Vermeld bij contact met [Living Security Support](mailto:support@livingsecurity.com) de organisatie, bron, stream, tijdstip van het verzoek, `runId` indien beschikbaar, en de responsstatus. Vermeld niet de toegangssleutel of de event-payload.

## Gerelateerd

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/nl/integrations/zscaler-zia-cloud-nss">
    Configureer een ondersteunde Zscaler-weblogfeed met de exacte bron, stream, headers en JSON-structuur.
  </Card>

  <Card title="API-toegangssleutels" icon="key" href="/nl/features/settings/api-keys">
    Maak scoped inloggegevens aan, roteer ze en trek ze in.
  </Card>

  <Card title="Signalen-gegevensbronnen" icon="wave-pulse" href="/nl/signals/data-sources">
    Lees hoe geïnterpreteerde integratieactiviteit Signalen ondersteunt.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.