> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Risikosignale

> Betrugserkennungssignale aus beliebigen Quellen aufnehmen, Identitätsereignisse in bewertete Signale normalisieren und diese nach Entität, Bewertung oder Typ abfragen.

Risikosignale ermöglichen es Ihnen, Betrugserkennungsdaten von jedem Upstream-Anbieter – Geräte-Fingerprinting-Diensten, IP-Reputations-APIs, E-Mail-Verifizierungstools, Dokumentenanalyse-Engines oder Ihren eigenen internen Regeln – in Truthlocks einzuspeisen. Nach der Erfassung sind die Signale über die API und die Seite **Risiko & Betrug > Signale** in der Konsole verfügbar.

> [!NOTE]
>
> Die Anti-Betrugs-Identitäts-Firewall ist **allgemein verfügbar**. Alle fünf Erkennungspfade – direkte Signalerfassung, Ereignisnormalisierung, Deepfake-Scanning, ATO-Erkennung und Geschwindigkeitsscore – sind in mehrsprachige API-Beispiele (cURL, JavaScript, Python), End-to-End-Anleitungen und Echtzeit-Webhook-Benachrichtigungen]\(/de/guides/webhooks) für alle Signaltypen integriert. Automatisierte Risikoentscheidungen]\(/de/api-reference/risk/evaluate), Fallmanagement]\(#case-management) und Betrugs-SIEM-Export]\(#siem-export) sind jetzt verfügbar.

Sie können Signale auf fünf Arten erstellen:

* **Direkte Erfassung** – senden Sie ein vollständig bewertetes Signal über `POST /v1/risk/signals`, wenn Sie bereits eine Risikobewertung von einem externen Anbieter haben. Unterstützt idempotente Wiederholungen über den `Idempotency-Key` Header.
* **Ereignisnormalisierung** – senden Sie ein rohes Identitätsereignis über `POST /v1/risk/events` und lassen Sie es von der Plattform automatisch einem Signaltyp und einer Basisbewertung zuordnen. Siehe [Ereignisnormalisierung](#event-normalization).
* **Deepfake- und Identitätsbetrugssignalbewertung** – Übermitteln Sie extern erzeugte Indikatoren oder Bewertungen zur Schwellenwertbewertung über `POST /v1/risk/deepfake/scan`. Scans, die 60 oder mehr erreichen, erfassen automatisch ein Risikosignal. Siehe den [Deepfake-Erkennungsleitfaden](https://docs.truthlocks.com/de/guides/deepfake-detection.md).
* **Erkennung von Kontoübernahmen** – bewerten Sie Anmeldeereignisse anhand geschwindigkeitsbasierter Heuristiken über `POST /v1/risk/ato/evaluate`. Warnungen werden erstellt und Risikosignale automatisch erfasst, wenn Schwellenwerte überschritten werden. Siehe den [ATO-Erkennungsleitfaden](https://docs.truthlocks.com/de/guides/ato-detection.md).
* **Geschwindigkeits- und Anomaliebewertung** – zeichnen Sie Subjektaktionen über `POST /v1/risk/velocity/record` auf und lassen Sie die Plattform die Häufigkeit über rollierende Zeitfenster (1 m, 5 m, 1 h, 24 h) verfolgen. Aktionen, die einen gewichteten Geschwindigkeitswert von 60 oder höher erzeugen, nehmen automatisch ein Risikosignal auf. Siehe die [Anleitung zur Geschwindigkeitsbewertung](https://docs.truthlocks.com/de/guides/velocity-scoring.md).

### Auswahl eines Erfassungspfads

| Szenario | Verwenden | Endpunkt |
| :- | :- | :- |
| Sie haben einen Risikowert von einem externen Betrugstool | Direkte Aufnahme | `POST /v1/risk/signals` |
| Sie möchten plattformnative Ereignisse (fehlgeschlagene Anmeldungen, Deepfake-Erkennungen) automatisch bewerten lassen | Ereignisnormalisierung | `POST /v1/risk/events` |
| Sie möchten bereitgestellte Deepfake- oder Imitationsindikatoren bewerten | Deepfake-Scan | `POST /v1/risk/deepfake/scan` |
| Sie möchten Kontoübernahmeversuche basierend auf der Anmeldegeschwindigkeit erkennen | ATO-Erkennung | `POST /v1/risk/ato/evaluate` |
| Sie möchten Geschwindigkeitsanomalien bei jeder Aktion erkennen | Geschwindigkeitsbewertung | `POST /v1/risk/velocity/record` |
| Sie verwenden mehrere Signalquellen | Alle fünf – Signale landen in derselben Pipeline | Jeder Endpunkt |

Alle fünf Pfade erzeugen dieselben Risikosignal-Datensätze. Sie können Signale von jedem Pfad mithilfe des [Listenendpunkts](https://docs.truthlocks.com/de/api-reference/risk-signals/list.md) und der Konsolenseite **Risiko & Betrug > Signale** abfragen, filtern und überprüfen.

## Funktionsweise

**1. Signale aufnehmen**

Senden Sie eine `POST` Anfrage an `/v1/risk/signals` mit der Signalquelle, dem Typ, dem Risikowert und dem zugehörigen Subjekt. Fügen Sie zusätzliche Kontextinformationen im `payload` Objekt bei.

**2. Abfragen und Filtern**

Verwenden Sie `GET /v1/risk/signals`, um Signale mit Filtern für Quelle, Signaltyp, Subjekt und Mindestpunktzahl aufzulisten. Die Ergebnisse werden mit Cursor-basierter Paginierung paginiert.

**3. In der Konsole überprüfen**

Öffnen Sie **Risiko & Betrug > Signale** in der Mandantenkonsole, um Signale zu durchsuchen, nach Quelle oder Score zu filtern und einzelne Signaldetails zu überprüfen.

## Voraussetzungen

* Ein aktiver Truthlocks-Mandant mit einem API-Schlüssel
* Mindestens eine Upstream-Betrugserkennungsquelle, die bewertete Signale erzeugt

## Erfassung eines Signals

Senden Sie eine `POST`-Anfrage mit den erforderlichen Feldern:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/signals \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "signal_source": "external",
    "signal_type": "velocity",
    "risk_score": 85,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f",
    "payload": {
      "ip": "203.0.113.42",
      "country": "US",
      "reason": "multiple_accounts_same_device"
    },
    "ip_address": "203.0.113.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/signals", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    signal_source: "external",
    signal_type: "velocity",
    risk_score: 85,
    subject_type: "user",
    subject_id: "usr_8f14e45f",
    payload: {
      ip: "203.0.113.42",
      country: "US",
      reason: "multiple_accounts_same_device",
    },
    ip_address: "203.0.113.42",
  }),
});
const signal = await response.json();
```

```python Python theme={null}
import httpx
import uuid

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/signals",
    headers={
        "X-API-Key": "tl_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "signal_source": "external",
        "signal_type": "velocity",
        "risk_score": 85,
        "subject_type": "user",
        "subject_id": "usr_8f14e45f",
        "payload": {
            "ip": "203.0.113.42",
            "country": "US",
            "reason": "multiple_accounts_same_device",
        },
        "ip_address": "203.0.113.42",
    },
)
signal = resp.json()
```

### Erforderliche Felder

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `signal_source` | string | Ursprung des Signals – `verification`, `login`, `attestation`, `external` oder `manual` |
| `signal_type` | string | Was erkannt wurde (z. B. `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`) |
| `risk_score` | integer | Risikobewertung von `0` (sicher) bis `100` (hohes Risiko). Bewertungen ab 80 lösen eine automatische Überprüfung aus. |
| `subject_type` | string | Entitätstyp: `user`, `issuer`, `attestation`, `session`, `ip` oder `device` |
| `subject_id` | string | Bezeichner der zu bewertenden Entität |

### Optionale Felder

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `payload` | object | Beliebiges JSON mit signalspezifischem Kontext (IP-Adressen, Geolocation, Gründe) |
| `ip_address` | string | Mit diesem Ereignis verknüpfte Quell-IP-Adresse |
| `user_agent` | string | Mit diesem Ereignis verknüpfter User-Agent-String |

### Idempotenz

Fügen Sie einen `Idempotency-Key`-Header (UUID) hinzu, um doppelte Signale bei Wiederholungsversuchen zu verhindern. Wenn Sie denselben Schlüssel zweimal senden, wird das Duplikat stillschweigend ignoriert.

## Signale abfragen

### Liste mit Filtern

```bash theme={null}
curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

Verfügbare Filter:

| Parameter | Beschreibung |
| :- | :- |
| `source` | Nach Signalquelle filtern |
| `signal_type` | Nach Signaltyp filtern |
| `subject_type` | Nach Subjekttyp filtern |
| `subject_id` | Nach Subjekt-ID filtern |
| `min_score` | Mindestpunkteschwelle (0–100) |
| `limit` | Ergebnisse pro Seite (max. 100) |
| `cursor` | Cursor für nächste Seite |

### Ein einzelnes Signal abrufen

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: tl_live_..."
```

## Console-Ansicht

Die Seite **Risiko & Betrug > Signale** in der Konsole bietet eine durchsuchbare, filterbare Liste aller erfassten Signale. Jede Zeile zeigt die Quelle, den Typ, den Score (farbcodiert nach Schweregrad), die Subjektreferenz und den Zeitstempel.

Verwenden Sie die Filter oben auf der Seite, um die Ergebnisse nach Quelle, Signaltyp oder Mindestpunktzahl einzugrenzen. Klicken Sie auf eine beliebige Zeile, um die vollständigen Signaldetails einschließlich des `payload`-Metadatenobjekts anzuzeigen.

## Bewertungsrichtlinien

Eine konsistente Bewertung über alle Quellen hinweg macht die nachgelagerte Analyse zuverlässiger. Wir empfehlen die folgenden Bereiche:

| Bereich | Interpretation | Beispiel |
| :- | :- | :- |
| 0 – 30 | Geringes Risiko | Bekanntes gutes Gerät, seriöse IP |
| 30 – 60 | Moderates Risiko | VPN-Nutzung, neue Konto-Geschwindigkeit |
| 60 – 80 | Hohes Risiko | Wegwerf-E-Mail, Rechenzentrums-IP |
| 80 – 100 | Kritisches Risiko | Bekanntes Betrugsgerät, unmögliche Reise |

> [!WARNING]
>
> Ergebnisse von 80 oder mehr lösen automatische Überprüfungsentscheidungen aus. Die Interpretation der Ergebnisse jenseits des automatischen Schwellenwerts liegt bei Ihnen – die Plattform speichert und gibt die Ergebnisse unverändert zurück und normalisiert nicht über verschiedene Quellen hinweg.

## Ereignisnormalisierung

Anstatt Risikosignale manuell zu konstruieren, können Sie Rohdaten von Identitätsereignissen übermitteln und die Plattform diese automatisch in Signale normalisieren lassen. Dies ist nützlich, wenn Sie plattform-eigene Ereignisse – fehlgeschlagene Anmeldungen, ungültige Signaturen, Deepfake-Verdächtige – direkt in die Risikopipeline einspeisen möchten, ohne sie selbst Signaltypen zuzuordnen.

Senden Sie eine `POST`-Anfrage an `/v1/risk/events` mit der Ereignisquelle, dem Typ und dem Betreff:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/events \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_source": "login",
    "event_type": "login.failed.repeated",
    "subject_id": "user_abc123",
    "ip_address": "198.51.100.42",
    "payload": { "attempt_count": 8, "window_seconds": 120 }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/events", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_source: "login",
    event_type: "login.failed.repeated",
    subject_id: "user_abc123",
    ip_address: "198.51.100.42",
    payload: { attempt_count: 8, window_seconds: 120 },
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/events",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "event_source": "login",
        "event_type": "login.failed.repeated",
        "subject_id": "user_abc123",
        "ip_address": "198.51.100.42",
        "payload": {"attempt_count": 8, "window_seconds": 120},
    },
)
result = resp.json()
```

Die Antwort enthält sowohl den rohen `event_id` als auch den normalisierten `signal_id`, sodass Sie die gesamte Pipeline vom Ereignis zum Signal verfolgen können:

```json theme={null}
{
  "event_id": "2a4b6c8d-...",
  "signal_id": "9f3a1c2d-...",
  "event_type": "login.failed.repeated",
  "signal_type": "ato",
  "risk_score": 70,
  "normalized": true,
  "created_at": "2027-05-01T10:00:00Z"
}
```

Wenn `normalized` `true` ist, stimmte das Ereignis mit einer bekannten Zuordnung überein. Wenn `false`, verwendete die Plattform den generischen Fallback.

### Eingebaute Ereigniszuordnungen

Die Plattform wird mit vorkalibrierten Zuordnungen für gängige Identitätsereignisse geliefert:

| Ereignistyp | Signaltyp | Basispunktzahl |
| :- | :- | :- |
| `verification.failed` | behavior | 60 |
| `verification.invalid_sig` | behavior | 75 |
| `login.failed.repeated` | ato | 70 |
| `login.suspicious_geo` | geo\_anomaly | 65 |
| `attestation.deepfake_suspect` | deepfake | 85 |
| `session.hijack_suspect` | ato | 90 |

Unbekannte Ereignistypen werden mit dem Signaltyp `behavior` und einem Basisscore von 10 akzeptiert.

### Ereignisfelder

**Erforderlich:**

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `event_source` | string | System, das das Ereignis generiert hat – `attestation`, `verification`, `login` oder `consumer_portal` |
| `event_type` | string | Roher Ereignisname (z. B. `login.failed.repeated`, `attestation.deepfake_suspect`) |
| `subject_id` | string | Bezeichner der am Ereignis beteiligten Entität |

**Optional:**

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `event_ref_id` | string | Externe Referenz-ID (Bestätigungs-ID, Sitzungs-ID) zur Querverweiskontrolle |
| `ip_address` | string | Quell-IP-Adresse |
| `payload` | object | Rohe Ereignisnutzlast für den Anreicherungskontext |

> [!NOTE]
>
> Verwenden Sie die Ereignisnormalisierung, wenn Ihre Ereignisse von innerhalb der Plattform stammen (Anmeldungen, Verifizierungen, Bestätigungen). Verwenden Sie den direkten [signal ingestion endpoint](https://docs.truthlocks.com/de/api-reference/risk/ingest-signal.md), wenn Sie bereits ein bewertetes Signal von einer externen Quelle haben.

## Mandantenisolation

Risikosignale sind vollständig mandantenisoliert unter Verwendung von [Row-Level Security (RLS)](https://docs.truthlocks.com/de/security/rls.md). Jedes Signal ist zum Zeitpunkt der Erfassung an den authentifizierten Mandanten gebunden, und Abfragen können nur Signale zurückgeben, die zum aufrufenden Mandanten gehören.

## Deepfake- und Imitationserkennung

Die [Deepfake-Erkennungs-API](https://docs.truthlocks.com/de/guides/deepfake-detection.md) erweitert die Risikosignal-Pipeline um automatisiertes Scannen nach manipulierten Inhalten und Identitätsbetrug. Senden Sie Bilder, Videos, Dokumente oder Attestierungen zur Analyse, und Scans, die den Risikoschwellenwert überschreiten, erzeugen automatisch ein Risikosignal – kein zusätzlicher API-Aufruf erforderlich.

Den vollständigen Workflow, die Indikatorreferenz und Codebeispiele finden Sie im [Handbuch zur Erkennung von Deepfakes und Identitätsdiebstahl](https://docs.truthlocks.com/de/guides/deepfake-detection.md).

## Erkennung von Kontoübernahmen

Die [ATO-Erkennungs-API](https://docs.truthlocks.com/de/guides/ato-detection.md) erweitert die Risikosignal-Pipeline um eine geschwindigkeitsbasierte Login-Überwachung. Senden Sie Login-Ereignisse an `POST /v1/risk/ato/evaluate`, und die Plattform verfolgt fehlgeschlagene Versuche pro Subjekt in einem rollierenden einstündigen Fenster. Wenn ein Subjekt einen Schwellenwert überschreitet (5, 10 oder 20 fehlgeschlagene Logins), wird ein Alarm erstellt und ein Risikosignal automatisch erfasst – kein zusätzlicher API-Aufruf erforderlich.

Den vollständigen Workflow, die Schwellenwertreferenz und die Integrationsmuster finden Sie im [Handbuch zur Erkennung von Kontoübernahmen](https://docs.truthlocks.com/de/guides/ato-detection.md).

## Geschwindigkeits- und Anomaliebewertung

Die [Geschwindigkeitsbewertungs-API](https://docs.truthlocks.com/de/guides/velocity-scoring.md) erweitert die Risikosignal-Pipeline um Multi-Window-Aktionsverfolgung und Anomalieerkennung. Erfassen Sie jede Subjektaktion über `POST /v1/risk/velocity/record`, und die Plattform verfolgt die Häufigkeit über vier rollierende Fenster (1 m, 5 m, 1 h, 24 h). Ein gewichteter Geschwindigkeitswert wird aus den Fensterzählungen berechnet, wobei kurze Fenster für die Burst-Erkennung bevorzugt werden. Wenn der Wert 60 oder höher erreicht, wird automatisch ein Risikosignal mit `signal_type: "velocity"` erfasst – kein zusätzlicher API-Aufruf erforderlich.

Den vollständigen Workflow, das Bewertungsmodell und die Integrationsmuster finden Sie im [Handbuch zur Geschwindigkeits- und Anomaliebewertung](https://docs.truthlocks.com/de/guides/velocity-scoring.md).

## Webhook-Benachrichtigungen

Risikosignale, die von einem der fünf Erkennungspfade erzeugt werden, können Echtzeit-[Webhook](https://docs.truthlocks.com/de/guides/webhooks.md)-Benachrichtigungen auslösen. Abonnieren Sie `risk.signal.created` oder `risk.signal.escalated`, um auf neue Signale zu reagieren, ohne abfragen zu müssen. Dies umfasst Signale aus direkter Erfassung, Ereignisnormalisierung, Deepfake-Scans, ATO-Warnungen und Geschwindigkeitsanomalien.

Beispiele für Nutzlasten und Integrationsmuster finden Sie im [Webhooks-Handbuch](https://docs.truthlocks.com/de/guides/webhooks.md#risk-signal-notifications).

## Nutzungsabrechnung

Anti-Betrugsfunktionen werden pro Abrechnungszyklus abgerechnet. Jeder Erkennungspfad erhöht seinen eigenen Nutzungszähler:

| Metrik | Gemessene Aktion |
| :- | :- |
| `antifraud.risk_signals` | Risikosignale aufgenommen oder generiert (alle fünf Pfade) |
| `antifraud.deepfake_scans` | Deepfake- und Imitations-Scan-Anfragen |
| `antifraud.velocity_records` | Datensätze für Geschwindigkeitsbewertungsaktionen |

Kontingente variieren je nach Planstufe. Sie können Ihren aktuellen Verbrauch mit der [Nutzungs-API](https://docs.truthlocks.com/de/api-reference/billing/usage.md) oder in der Konsole unter **Einstellungen > Abrechnung > Nutzung** im Abschnitt **Betrugsbekämpfung** überprüfen. Um zu überprüfen, ob ein bestimmter Vorgang zulässig ist, bevor Sie ihn ausführen, verwenden Sie den [Limit-Check-Endpunkt](https://docs.truthlocks.com/de/api-reference/billing/entitlements.md).

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

Die Antwort enthält alle Anti-Betrugs-Zähler mit den Feldern `used`, `limit` und `period`, damit Sie den Verbrauch programmatisch überwachen können.

> [!NOTE]
>
> Eine vollständige Liste der 16 kostenpflichtigen Produkte und ihrer Standardtarife finden Sie in der [Abrechnungsübersicht](https://docs.truthlocks.com/de/billing/overview.md#metered-products).

## Was als Nächstes kommt

* [Leitfaden zur Geschwindigkeits- und Anomaliebewertung](https://docs.truthlocks.com/de/guides/velocity-scoring.md)
* [Leitfaden zur Erkennung von Kontoübernahmen](https://docs.truthlocks.com/de/guides/ato-detection.md)
* [Leitfaden zur Erkennung von Deepfakes und Identitätsdiebstahl](https://docs.truthlocks.com/de/guides/deepfake-detection.md)
* [API-Referenz zur Aufnahme von Risikosignalen](https://docs.truthlocks.com/api-reference/risk-signals/ingest)
* [API-Referenz zur Normalisierung von Identitätsereignissen](https://docs.truthlocks.com/de/api-reference/risk/normalize-event.md)
* [API-Referenz zum Auflisten von Risikosignalen](https://docs.truthlocks.com/de/api-reference/risk-signals/list.md)
* [API-Referenz zum Abrufen von Risikosignalen](https://docs.truthlocks.com/de/api-reference/risk-signals/get.md)
* [Sicherheit auf Zeilenebene](https://docs.truthlocks.com/de/security/rls.md)


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