Custom Push Source API

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

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.

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.

1. Quelle und Streams registrieren

Custom Push Source öffnen

Gehen Sie zu Einstellungen → Integrationen → Catalog, suchen Sie Custom Push Source und wählen Sie Zusatz.

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.

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.

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.

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.

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.

string

erforderlich

Der registrierte Quellname. Verwenden Sie 1–64 Kleinbuchstaben, Ziffern oder Bindestriche, beginnend mit einem Buchstaben oder einer Ziffer.

string

erforderlich

Der registrierte Stream-Name. Es gelten dieselben Regeln, zusätzlich sind Unterstriche zulässig.

string

erforderlich

Senden Sie den Push-Ingest-Zugriffsschlüssel als Bearer <access-key>.

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.

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.

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.

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'

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

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

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.

string

erforderlich

Die Run-ID für diesen angenommenen Batch. Bewahren Sie sie auf, um den Verarbeitungsstatus zu prüfen.

number

erforderlich

Die Anzahl der angenommenen und gespeicherten Datensätze.

string

erforderlich

Der für diesen Push verwendete Quellname.

string

erforderlich

Der für diesen Push verwendete Stream-Name.

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.

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.

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

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.

API-Zugriffsschlüssel

Erstellen, rotieren und widerrufen Sie Zugangsdaten mit begrenztem Geltungsbereich.

Signal-Datenquellen

Erfahren Sie, wie interpretierte Integrationsaktivitäten Signale unterstützen.

Integrationen

Integrationseinrichtung

Katalog

Ausgehende Kanäle

Vorbereitung

1. Quelle und Streams registrieren

2. Push-Ingest-Schlüssel erstellen

3. Regionalen Endpunkt auswählen

Anfragetext

4. JSON-Batch senden

Stattdessen CSV senden

Anfragelimits und Wiederholungen

Datenfluss überprüfen

Checkliste zur Fehlerbehebung

Weiterführende Informationen

Zscaler ZIA Cloud NSS

API-Zugriffsschlüssel

Signal-Datenquellen

Integrationen

Integrationseinrichtung

Katalog

Ausgehende Kanäle

​Vorbereitung

​1. Quelle und Streams registrieren

​2. Push-Ingest-Schlüssel erstellen

​3. Regionalen Endpunkt auswählen

​Anfragetext

​4. JSON-Batch senden

​Stattdessen CSV senden

​Anfragelimits und Wiederholungen

​Datenfluss überprüfen

​Checkliste zur Fehlerbehebung

​Weiterführende Informationen

Zscaler ZIA Cloud NSS

API-Zugriffsschlüssel

Signal-Datenquellen

Vorbereitung

1. Quelle und Streams registrieren

2. Push-Ingest-Schlüssel erstellen

3. Regionalen Endpunkt auswählen

Anfragetext

4. JSON-Batch senden

Stattdessen CSV senden

Anfragelimits und Wiederholungen

Datenfluss überprüfen

Checkliste zur Fehlerbehebung

Weiterführende Informationen