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

# Mukautetun push-lähteen API

> Rekisteröi lähde ja lähetä JSON- tai CSV-tapahtte­ryhmiä Living Securityyn rajatun käyttöoikeuden API-avaimella.

Käytä mukautettua push-lähdettä (Custom Push Source), kun järjestelmä lähettää tietueita Living Securityyn sen sijaan, että Luettelon liitin hakisi ne kyselemällä. Lähettäjä voi toimittaa JSON-taulukoita tai CSV-tiedostoja alueelliseen HTTPS-päätepisteeseen.

## Ennen aloittamista

Tarvitset seuraavat:

* oikeuden hallita integraatioita ja käyttöoikeusavaimia Living Securityssa
* palvelinpuolen lähettäjän, joka pystyy tekemään HTTPS-`POST`-pyyntöjä
* organisaatiosi Living Security -alueen
* vakaan lähteen nimen ja vähintään yhden virran nimen

Lähteiden ja virtojen nimet ovat pysyviä reititysavaimia. Lähteen nimen on oltava 1–64 merkkiä pitkä, ja se saa sisältää vain pieniä kirjaimia, numeroita tai yhdysmerkkejä. Virran nimessä sallitaan lisäksi alaviivat. Molempien on alettava kirjaimella tai numerolla.

<Warning>
  Käsittele API-käyttöoikeusavainta salaisuutena. Älä sijoita sitä selaimessa suoritettavaan koodiin, älä vie sitä
  versionhallintaan äläkä lähetä sitä tukipyynnössä.
</Warning>

## 1. Rekisteröi lähde ja virrat

<Steps>
  <Step title="Avaa Custom Push Source">
    Siirry kohtaan **Asetukset → Integraatiot → Luettelo**, etsi **Custom Push Source** ja valitse **Lisää**.
  </Step>

  <Step title="Anna lähteelle nimi">
    Anna lähteen reititysavain ja valinnainen kuvaus. Käytä esimerkiksi arvoa `custom-phishing-sim` äläkä välilyöntejä sisältävää näyttönimeä.
  </Step>

  <Step title="Lisää virrat">
    Lisää jokainen virta, jota lähettäjä käyttää. Lähde–virta-parin on oltava olemassa ennen ensimmäistä lähetystä; tuntematon pari palauttaa vastauksen `404 Not Found`.
  </Step>

  <Step title="Tallenna lähde">
    Avaa luomisen jälkeen lähde kohdasta **Asetukset → Integraatiot → yhdistetty**. Sen **Push via API** -näkymä näyttää päätepisteen mallin ja viimeisimmät ajot.
  </Step>
</Steps>

## 2. Luo push-ingest-avain

Siirry kohtaan **Asetukset → Access Keys**, valitse **Create Access Key** ja valitse käyttöoikeusalue **Push Ingest**. Kopioi luotu arvo heti; se näytetään vain kerran.

Avain on sidottu yhteen Living Security -organisaatioon. Push-pyyntö ei tarvitse organisaatio-otsikkoa. Katso avainten kierrätys ja mitätöinti kohdasta [API-käyttöoikeusavaimet](/fi/features/settings/api-keys).

## 3. Valitse alueellinen päätepiste

Käytä organisaatiosi Living Security -isäntänimeä:

| Alue | Perus-URL |
| - | - |
| Yhdysvallat | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Euroopan unioni | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Liitä loppuun `/push-ingest/{integrationKey}/{streamName}`. Polku on kirjainkokoriippuvainen, ja sen on vastattava täsmälleen rekisteröityä lähdettä ja virtaa.

<ParamField path="integrationKey" type="string" required>
  Rekisteröity lähteen nimi. Käytä 1–64 pientä kirjainta, numeroa tai yhdysmerkkiä, ja aloita kirjaimella tai numerolla.
</ParamField>

<ParamField path="streamName" type="string" required>
  Rekisteröity virran nimi. Samat säännöt pätevät, ja lisäksi alaviivat ovat sallittuja.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Lähetä push-ingest-käyttöoikeusavain muodossa `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Käytä arvoa `application/json` JSON-datalle tai `text/csv` CSV-datalle. Palvelin voi myös tunnistaa JSON-taulukon, jos tämä otsikko jätetään pois.
</ParamField>

<ParamField header="x-organization-id" type="string">
  Valinnainen organisaation UUID. Käyttöoikeusavain määrittää organisaation jo itsessään. Jos lähetät tämän otsikon, sen on vastattava avaimen organisaatiota; sillä ei voi valita toista organisaatiota.
</ParamField>

### Pyynnön runko

Lähetä ylimmän tason ei-tyhjä JSON-objektitaulukko tai CSV-tiedoston tavut otsikkorivillä. Nimettyä JSON-käärekenttää ei ole. Yksi erä voi sisältää enintään 10 000 tietuetta ja 10 MB.

## 4. Lähetä JSON-erä

Lähetä ei-tyhjä JSON-taulukko, jonka alkiot ovat objekteja. `Content-Type: application/json` on suositeltava, ja monet lähettävät tuotteet edellyttävät sitä, vaikka Living Security pystyy tunnistamaan taulukkorungon ilman sitä.

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

Onnistunut pyyntö palauttaa vastauksen `202 Accepted`. Virhevälilehti näyttää vastauksen `400 Bad Request`, kun JSON-runko on virheellisesti muodostettu:

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

Hyväksyntä tarkoittaa, että erä on tallennettu asynkronista käsittelyä varten. Se ei tarkoita, että jokainen tietue olisi jo tulkittu toiminnaksi.
Korjaa esimerkissä `400` JSON tai lähetä CSV-data otsikolla `Content-Type: text/csv` ja yritä sitten uudelleen.

<ResponseField name="runId" type="string" required>
  Tämän hyväksytyn erän ajon tunnus. Säilytä se käsittelyn tilan tarkistamista varten.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Hyväksyttyjen ja tallennettujen tietueiden määrä.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Tässä lähetyksessä käytetty lähteen nimi.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Tässä lähetyksessä käytetty virran nimi.
</ResponseField>

## Lähetä sen sijaan CSV

Aseta `Content-Type: text/csv` ja lähetä tiedoston tavut, kuten yllä olevassa **CSV file** -pyyntöesimerkissä on esitetty. Ensimmäinen rivi määrittää kenttien nimet.

Totuusarvoteksti muunnetaan totuusarvoksi ja tavallinen numeroteksti luvuksi. Etunollalliset arvot, turvattoman suuret kokonaisluvut, päivämäärät ja muu teksti säilyvät merkkijonoina. Tyhjä solu jättää kentän pois. Virheelliset rivit, pariton lainausmerkkien määrä ja UTF-16-tiedostot hylätään.

## Pyyntörajat ja uudelleenyritykset

| Sopimus | Nykyinen arvo |
| - | - |
| Tietueiden enimmäismäärä | 10 000 pyyntöä kohden |
| Pyynnön rungon enimmäiskoko | 10 MB |
| Organisaatiokohtainen pyyntötiheys | 600 pyyntöä 60 sekunnissa |

Jaa suuremmat viennit erin, jotka täyttävät molemmat rajat. Odota kutakin vastausta ja säilytä palautettu `runId` lähettäjän lokeissa.

| Vastaus | Merkitys | Lähettäjän toimenpide |
| - | - | - |
| `202` | Erä hyväksytty | Kirjaa `runId` ylös; älä lähetä uudelleen heti |
| `400` | Virheellinen nimi, JSON, CSV, tietuemäärä tai runko | Korjaa pyyntö; älä yritä uudelleen muuttumattomana |
| `401` | Avain puuttuu, on vanhentunut, mitätöity tai virheellinen | Vaihda avain ja käytä Bearer-otsikkoa |
| `403` | Avaimelta puuttuu vaadittu käyttöoikeusalue | Luo avain, jolla on **Push Ingest** -käyttöoikeusalue |
| `404` | Lähdettä tai virtaa ei ole rekisteröity | Rekisteröi täsmälleen oikea pari tai korjaa URL |
| `413` | Pyynnön runko ylittää 10 MB | Jaa erä pienempiin pyyntöihin |
| `429` | Tilapäinen IP-tason rajoitus | Noudata otsikkoa `Retry-After`, jos se on annettu, ja hidasta lähetystä |
| `503` | Organisaation pyyntökiintiö tai rajoitin ei ole käytettävissä | Odota ajan `Retry-After` kuluminen ja lähetä sama erä uudelleen |

Tavallinen todennetun organisaation raja palauttaa vastauksen `503`, ei `429`, joten webhook-lähettäjät käsittelevät sen uudelleen yritettävänä. Vastaus `503` palautetaan ennen kuin erä tallennetaan; saman erän lähettäminen uudelleen ilmoitetun ajan kuluttua ei monista hyväksyttyä ajoa.

## Varmista tiedonkulku

Avaa Custom Push Source ja tarkista **Push History**. Varmista virta, tietueiden määrä, avaimen yhteys ja käsittelyn tila. Data, jolle on ylläpidetty tulkki, voi tämän jälkeen muuttua henkilöiksi ja normalisoiduksi toiminnaksi. Data ilman tulkkia säilyy tallennettuna, mutta ei tuota toimintaa.

<Info>
  Käytä täsmällisiä kenttien nimiä ja hyötykuorman rakennetta palveluntarjoajakohtaisesta
  oppaasta, jos sellainen on olemassa. Onnistunut `202` todistaa toimituksen, ei sitä, että
  mielivaltainen skeema vastaisi Living Securityn toimintaa.
</Info>

## Vianmäärityksen tarkistuslista

* Kopioi päätepiste oikeasta lähteestä ja korvaa virran paikkamerkki.
* Lähetä käyttöoikeusavain muodossa `Authorization: Bearer …`; `x-api-key` ei ole hyväksytty.
* Varmista, että runko on ylimmän tason JSON-taulukko, ei yksittäinen objekti eikä tietueiden ympärillä oleva kääre.
* Varmista lähteen ja virran kirjoitusasu, mukaan lukien yhdysmerkit, alaviivat ja kirjainkoko.
* Tarkista **Push History** ennen sellaisen erän uudelleenlähettämistä, jonka vastaus katosi.
* Kun otat yhteyttä [Living Securityn tukeen](mailto:support@livingsecurity.com), liitä mukaan organisaatio, lähde, virta, pyynnön ajankohta, `runId` jos saatavilla, sekä vastauksen tila. Älä liitä mukaan käyttöoikeusavainta tai tapahtuman hyötykuormaa.

## Liittyvää

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/fi/integrations/zscaler-zia-cloud-nss">
    Määritä tuettu Zscaler-verkkolokisyöte täsmällisellä lähteellä, virralla, otsikoilla ja JSON-rakenteella.
  </Card>

  <Card title="API-käyttöoikeusavaimet" icon="key" href="/fi/features/settings/api-keys">
    Luo, kierrätä ja mitätöi rajattuja tunnistetietoja.
  </Card>

  <Card title="Signaalien tietolähteet" icon="wave-pulse" href="/fi/signals/data-sources">
    Lue, miten tulkittu integraatiotoiminta tukee signaaleja.
  </Card>
</CardGroup>


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