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

> Registrieren Sie eine Quelle und senden Sie JSON- oder CSV-Ereignisbatches mit einem Zugriffsschlüssel mit begrenztem Geltungsbereich an Living Security.

Verwenden Sie eine Custom Push Source, wenn ein System Datensätze an Living Security sendet, anstatt von einem Catalog-Connector abgefragt zu werden. Der Sender kann JSON-Arrays oder CSV-Dateien an einen regionalen HTTPS-Endpunkt übermitteln.

## Vorbereitung

Sie benötigen:

* die Berechtigung zum Verwalten von Integrationen und Zugriffsschlüsseln in Living Security
* einen serverseitigen Sender, der HTTPS-`POST`-Anfragen senden kann
* die Living Security-Region Ihrer Organisation
* einen stabilen Quellnamen und mindestens einen Stream-Namen

Quellnamen und Stream-Namen sind dauerhafte Routing-Schlüssel. Quellnamen müssen aus 1–64 Kleinbuchstaben, Ziffern oder Bindestrichen bestehen. Bei Stream-Namen sind zusätzlich Unterstriche zulässig. Beide müssen mit einem Buchstaben oder einer Ziffer beginnen.

<Warning>
  Behandeln Sie den API-Zugriffsschlüssel als Geheimnis. Legen Sie ihn nicht im Browsercode ab, committen Sie ihn
  nicht in die Versionsverwaltung und senden Sie ihn nicht in einem Support-Ticket.
</Warning>

## 1. Quelle und Streams registrieren

<Steps>
  <Step title="Custom Push Source öffnen">
    Gehen Sie zu **Einstellungen → Integrationen → Catalog**, suchen Sie **Custom Push Source** und wählen Sie **Zusatz**.
  </Step>

  <Step title="Quelle benennen">
    Geben Sie den Routing-Schlüssel der Quelle und optional eine Beschreibung ein. Verwenden Sie beispielsweise `custom-phishing-sim` statt eines Anzeigenamens mit Leerzeichen.
  </Step>

  <Step title="Streams hinzufügen">
    Fügen Sie jeden Stream hinzu, den der Sender verwenden wird. Das Paar aus Quelle und Stream muss vor dem ersten Push existieren; ein unbekanntes Paar führt zu `404 Not Found`.
  </Step>

  <Step title="Quelle speichern">
    Öffnen Sie die Quelle nach dem Erstellen unter **Einstellungen → Integrationen → Verbunden**. Die Ansicht **Push via API** zeigt das Endpunktmuster und die letzten Durchläufe.
  </Step>
</Steps>

## 2. Push-Ingest-Schlüssel erstellen

Gehen Sie zu **Einstellungen → Access Keys**, wählen Sie **Create Access Key** und wählen Sie den Geltungsbereich **Push Ingest**. Kopieren Sie den generierten Wert sofort; er wird nur einmal angezeigt.

Der Schlüssel ist an eine Living Security-Organisation gebunden. Die Push-Anfrage benötigt keinen Organisations-Header. Informationen zu Rotation und Widerruf finden Sie unter [API-Zugriffsschlüssel](/de/features/settings/api-keys).

## 3. Regionalen Endpunkt auswählen

Verwenden Sie den Hostnamen für die Living Security-Organisation:

| Region | Basis-URL |
| - | - |
| Vereinigte Staaten | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| Europäische Union | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Hängen Sie `/push-ingest/{integrationKey}/{streamName}` an. Beim Pfad wird zwischen Groß- und Kleinschreibung unterschieden, und er muss exakt mit der registrierten Quelle und dem registrierten Stream übereinstimmen.

<ParamField path="integrationKey" type="string" required>
  Der registrierte Quellname. Verwenden Sie 1–64 Kleinbuchstaben, Ziffern oder Bindestriche, beginnend mit einem Buchstaben oder einer Ziffer.
</ParamField>

<ParamField path="streamName" type="string" required>
  Der registrierte Stream-Name. Es gelten dieselben Regeln, zusätzlich sind Unterstriche zulässig.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Senden Sie den Push-Ingest-Zugriffsschlüssel als `Bearer <access-key>`.
</ParamField>

<ParamField header="Content-Type" type="string">
  Verwenden Sie `application/json` für JSON oder `text/csv` für CSV. Der Server kann ein JSON-Array auch erkennen, wenn dieser Header weggelassen wird.
</ParamField>

<ParamField header="x-organization-id" type="string">
  Optionale Organisations-UUID. Der Zugriffsschlüssel bestimmt die Organisation bereits. Wenn Sie diesen Header senden, muss er mit der Organisation des Schlüssels übereinstimmen; er kann keine andere Organisation auswählen.
</ParamField>

### Anfragetext

Senden Sie ein nicht leeres JSON-Array von Objekten auf oberster Ebene oder CSV-Dateibytes mit einer Kopfzeile. Es gibt kein benanntes JSON-Wrapper-Feld. Jeder Batch kann bis zu 10,000 Datensätze und 10 MB enthalten.

## 4. JSON-Batch senden

Senden Sie ein nicht leeres JSON-Array, dessen Elemente Objekte sind. `Content-Type: application/json` wird empfohlen und von vielen sendenden Produkten vorausgesetzt, obwohl Living Security einen Array-Body auch ohne diesen Header erkennen kann.

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

Eine erfolgreiche Anfrage liefert `202 Accepted` zurück. Der Fehler-Tab zeigt ein `400 Bad Request`, wenn der JSON-Body fehlerhaft ist:

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

Die Annahme bedeutet, dass der Batch zur asynchronen Verarbeitung gespeichert wurde. Sie bedeutet nicht, dass bereits jeder Datensatz in Aktivitäten interpretiert wurde.
Korrigieren Sie beim Beispiel `400` das JSON oder senden Sie CSV mit `Content-Type: text/csv` und versuchen Sie es dann erneut.

<ResponseField name="runId" type="string" required>
  Die Run-ID für diesen angenommenen Batch. Bewahren Sie sie auf, um den Verarbeitungsstatus zu prüfen.
</ResponseField>

<ResponseField name="recordsAccepted" type="number" required>
  Die Anzahl der angenommenen und gespeicherten Datensätze.
</ResponseField>

<ResponseField name="integrationKey" type="string" required>
  Der für diesen Push verwendete Quellname.
</ResponseField>

<ResponseField name="streamName" type="string" required>
  Der für diesen Push verwendete Stream-Name.
</ResponseField>

## Stattdessen CSV senden

Setzen Sie `Content-Type: text/csv` und senden Sie die Dateibytes, wie im obigen Anfragebeispiel **CSV file** gezeigt. Die erste Zeile liefert die Feldnamen.

Boolescher Text wird zu einem Boolean, und gewöhnlicher numerischer Text wird zu einer Zahl. Werte mit führenden Nullen, nicht sichere große Ganzzahlen, Datumsangaben und anderer Text bleiben Zeichenfolgen. Bei leeren Zellen wird das jeweilige Feld ausgelassen. Fehlerhafte Zeilen, nicht geschlossene Anführungszeichen und UTF-16-Dateien werden abgelehnt.

## Anfragelimits und Wiederholungen

| Vorgabe | Aktueller Wert |
| - | - |
| Maximale Anzahl Datensätze | 10,000 pro Anfrage |
| Maximaler Anfragetext | 10 MB |
| Anfragerate pro Organisation | 600 Anfragen pro 60 Sekunden |

Teilen Sie größere Exporte in Batches auf, die beide Limits einhalten. Warten Sie auf jede Antwort und speichern Sie den zurückgegebenen Wert `runId` in den Logs des Senders.

| Antwort | Bedeutung | Maßnahme des Senders |
| - | - | - |
| `202` | Batch angenommen | `runId` festhalten; nicht sofort erneut senden |
| `400` | Ungültiger Name, ungültiges JSON oder CSV, ungültige Datensatzanzahl oder ungültiger Body | Anfrage korrigieren; nicht unverändert wiederholen |
| `401` | Fehlender, abgelaufener, widerrufener oder ungültiger Schlüssel | Schlüssel ersetzen und den Bearer-Header verwenden |
| `403` | Dem Schlüssel fehlt der erforderliche Geltungsbereich | Schlüssel mit dem Geltungsbereich **Push Ingest** erstellen |
| `404` | Quelle oder Stream ist nicht registriert | Exaktes Paar registrieren oder URL korrigieren |
| `413` | Anfragetext überschreitet 10 MB | Batch in kleinere Anfragen aufteilen |
| `429` | Vorübergehende Drosselung auf IP-Ebene | `Retry-After` beachten, falls vorhanden, und die Senderate reduzieren |
| `503` | Ratenbegrenzung der Organisation oder Limiter nicht verfügbar | Auf `Retry-After` warten und denselben Batch erneut senden |

Das normale Limit für authentifizierte Organisationen liefert `503` statt `429` zurück, sodass Webhook-Sender es als wiederholbar behandeln. Ein `503` wird zurückgegeben, bevor der Batch gespeichert wird; das erneute Senden desselben Batches nach dem angegebenen Intervall führt nicht zu einem doppelten angenommenen Durchlauf.

## Datenfluss überprüfen

Öffnen Sie die Custom Push Source und prüfen Sie **Push History**. Bestätigen Sie Stream, Datensatzanzahl, Schlüsselzuordnung und Verarbeitungsstatus. Daten mit einem gepflegten Interpreter können anschließend zu Personen und normalisierten Aktivitäten werden. Daten ohne Interpreter bleiben gespeichert, erzeugen aber keine Aktivität.

<Info>
  Verwenden Sie die exakten Feldnamen und die Payload-Struktur aus dem anbieterspezifischen Leitfaden, sofern
  einer existiert. Ein erfolgreiches `202` belegt die Zustellung, nicht dass ein beliebiges Schema
  auf Living Security-Aktivitäten abgebildet wird.
</Info>

## Checkliste zur Fehlerbehebung

* Kopieren Sie den Endpunkt aus der richtigen Quelle und ersetzen Sie den Stream-Platzhalter.
* Senden Sie den Zugriffsschlüssel als `Authorization: Bearer …`; `x-api-key` wird nicht akzeptiert.
* Stellen Sie sicher, dass der Body ein JSON-Array auf oberster Ebene ist, kein einzelnes Objekt und keine Hülle um die Datensätze.
* Prüfen Sie die Schreibweise von Quelle und Stream, einschließlich Bindestrichen, Unterstrichen und Groß-/Kleinschreibung.
* Prüfen Sie **Push History**, bevor Sie einen Batch erneut senden, dessen Antwort verloren gegangen ist.
* Wenn Sie den [Living Security Support](mailto:support@livingsecurity.com) kontaktieren, geben Sie Organisation, Quelle, Stream, Anfragezeitpunkt, `runId` (sofern verfügbar) und Antwortstatus an. Geben Sie weder den Zugriffsschlüssel noch die Ereignis-Payload an.

## Weiterführende Informationen

<CardGroup cols={2}>
  <Card title="Zscaler ZIA Cloud NSS" icon="shield" href="/de/integrations/zscaler-zia-cloud-nss">
    Konfigurieren Sie einen unterstützten Zscaler-Web-Log-Feed mit der exakten Quelle, dem Stream, den Headern und der JSON-Struktur.
  </Card>

  <Card title="API-Zugriffsschlüssel" icon="key" href="/de/features/settings/api-keys">
    Erstellen, rotieren und widerrufen Sie Zugangsdaten mit begrenztem Geltungsbereich.
  </Card>

  <Card title="Signal-Datenquellen" icon="wave-pulse" href="/de/signals/data-sources">
    Erfahren Sie, wie interpretierte Integrationsaktivitäten Signale unterstützen.
  </Card>
</CardGroup>


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