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

# Event-Ingestion-API: Nicht-monetäre Ereignisse

> Senden Sie nicht-monetäre Aktivitäten – Logins, Gameplay, Boni, Zahlungen, Streitfälle, Kontosicherheit – an dieselbe Engine, die Ihre Transaktionen bewertet.

Transaktionen sind das Geld. Ereignisse sind alles Übrige, was Ihre Plattform weiß: der Login, der der Auszahlung vorausging, die Hand, die Chips zwischen zwei Konten verschob, der Bonus, der zweimal beansprucht wurde, der Chargeback, der eine Woche später einging.

Ereignisse verwenden für jede Kategorie denselben Envelope, sind von Haus aus idempotent und werden von [derselben Regel-Engine](https://docs.didit.me/de/transaction-monitoring/event-rules.md) ausgewertet, die auch Ihre [Transaktionen](https://docs.didit.me/de/transaction-monitoring/transactions.md) bewertet.

> [!NOTE]
>
> Die Erfassung von Ereignissen ist optional (Opt-in). Aktivieren Sie sie unter **Transactions → Settings → Event monitoring**.
> Solange Sie das nicht tun, ändert sich nichts: Ihre bestehenden Transaktionsregeln greifen weiterhin nur bei Transaktionen, und eine Ereignisregel kann nicht versehentlich entstehen, da eine Regel nur für Transaktionen gilt, sofern Sie Ereignisse nicht ausdrücklich einschließen.
>
> Solange die Erfassung nicht aktiviert ist, antwortet jeder Schreibpfad, nämlich `POST /v3/events/`, `POST /v3/events/batch/`, `POST /v3/events/sdk-token/` und der Geräte-Pfad `/v1/events/`, mit `403` und `{"code": "event_monitoring_disabled"}`. Es wird nichts gespeichert, angereichert oder ausgewertet. Lesezugriffe sind nicht betroffen.

## Endpoints

| Endpoint | Authentifizierung | Verwendung für |
| - | - | - |
| `POST /v3/events/` | API-Schlüssel | Ein Ereignis aus Ihrem Backend |
| `POST /v3/events/batch/` | API-Schlüssel | Bis zu 500 Ereignisse in einer Anfrage |
| `POST /v3/events/sdk-token/` | API-Schlüssel | Eine Geräteberechtigung mit eingeschränktem Umfang erzeugen |
| `POST /v1/events/` | `X-Monitoring-Token` | Ein Ereignis aus dem Device-SDK |
| `POST /v1/events/batch/` | `X-Monitoring-Token` | Ein übermittelter SDK-Puffer |
| `GET /v3/events/` | API-Schlüssel | Ereignisse auflisten und filtern |
| `GET /v3/events/{event_uuid}/` | API-Schlüssel | Ein Ereignis mit seinen Regelnachweisen |
| `GET /v3/events/subjects/{vendor_data}/` | API-Schlüssel | Die Zeitachse eines Subjekts (siehe `entity_type` unten) |
| `GET /v3/events/enrichment-metrics/` | API-Schlüssel | Zustand des IP-Anreicherungs-Cache |

Der `/v3/`-Pfad ist der Server-Pfad und verwendet dieselbe `x-api-key`-Authentifizierung wie der Rest der Transaktions-API. Der `/v1/events/`-Pfad ist der Geräte-Pfad, siehe [Übermittlung von SDK-Ereignissen](https://docs.didit.me/de/transaction-monitoring/sdk-event-submission.md).

## Aufbau des Envelopes

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'
```

```json theme={null}
{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}
```

| Feld | Pflicht | Hinweise |
| - | - | - |
| `event_id` | ja | Ihre eigene Kennung, eindeutig pro Anwendung. Sie ist der Idempotenzschlüssel. |
| `event_category` | ja | Eine der zehn Kategorien unten. |
| `action_type` | ja | Freier String, bis zu 128 Zeichen. |
| `occurred_at` | ja | Wann das Ereignis bei Ihnen stattfand. Bis zu 7 Tage in der Vergangenheit, bis zu 5 Minuten in der Zukunft. |
| `subject.vendor_data` | ja | Ihre Benutzer-ID. Wird auf denselben Benutzer aufgelöst, auf den auch eine Transaktion aufgelöst würde. |
| `subject.entity_type` | nein | `individual` (Standard) oder `company`. |
| `business.vendor_data` | nein | Das Unternehmen, zu dem das Ereignis gehört. |
| `session` | nein | `session_id`, `sequence`, `page_url`, `referrer`. |
| `device_context` | nein | `fingerprint`, `persistent_device_id`, `bot_score` und `network_context.ip_address`. |
| `transaction_context` | nein | `amount`, `currency`, `direction`, `payment_reference_id`. |
| `payload` | nein | Die fachlichen Felder der Kategorie. Bis zu 16 KB. |
| `custom_values` | nein | Bis zu 100 skalare Schlüssel, in Regeln als `custom_values.<key>` ansprechbar. |

## Kategorien

Zehn vollwertige Kategorien mit typisierter Validierung und verwalteten [Regelfeldern](https://docs.didit.me/de/transaction-monitoring/event-rules.md#ereignisfelder).

| Kategorie | Typische Aktionen |
| - | - |
| `auth` | `signup`, `login`, `login_failed`, `logout`, `password_forgot`, `password_reset`, `mfa_reset`, `mfa_challenge` |
| `session` | `session_started`, `session_ended`, `page_view`, `sdk_loaded`, `device_seen`, `bot_signal_observed`, `sdk_heartbeat` |
| `gameplay` | `round_started`, `round_completed`, `bet_placed`, `bet_settled`, `cashout`, `limit_change`, `p2p_settlement` |
| `bonus` | `bonus_claimed`, `bonus_wagered`, `bonus_released`, `promotion_viewed` |
| `affiliate` | `affiliate_attributed`, `referral_clicked`, `campaign_joined`, `commission_event` |
| `payment` | `deposit_initiated`, `deposit_completed`, `withdrawal_requested`, `withdrawal_completed`, `withdrawal_address_changed`, `payment_instrument_seen` |
| `dispute` | `chargeback_opened`, `chargeback_won`, `chargeback_lost`, `refund_issued`, `payment_dispute_updated` |
| `security` | `login_attempt`, `login_succeeded`, `login_failed`, `password_changed`, `mfa_changed`, `credential_reset`, `country_changed`, `device_changed`, `account_locked` |
| `responsible_gambling` | `self_exclusion_checked`, `self_exclusion_match`, `re_registration_attempt`, `limit_breach_attempt`, `registry_status_changed` |
| `custom` | Alles, was Sie definieren |

`auth` ist die breite Produktkategorie; `security` ist die risikorelevante Teilmenge mit dem geordneten Lebenszyklus, den Regeln zur Kontoübernahme auswerten.

### Pflicht-Payload-Schlüssel

Manche Aktionen lassen sich ohne bestimmte Schlüssel nicht korrelieren. Die Validierung weist sie daher ab, statt Nachweise zu speichern, die niemand zuordnen kann.

| Aktion | Pflichtfelder |
| - | - |
| `gameplay.p2p_settlement` | `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role`, und eines der Felder `hand_id`, `round_id` oder `match_id` |
| `gameplay.bet_placed`, `gameplay.bet_settled` | `game_id` |
| `payment.deposit_*`, `payment.withdrawal_completed`, `payment.withdrawal_requested`, `payment.deposit_initiated` | `payment_reference_id`, `amount`, `currency`, `payment_method`, `status` |
| `payment.withdrawal_address_changed` | `withdrawal_address_hash` |
| `dispute.chargeback_*` | `payment_reference_id`, und eines der Felder `dispute_id` oder `chargeback_id` |
| `security.*_changed` | `changed_field`; Änderungen an Konto- oder Auszahlungssteuerung benötigen zusätzlich `previous_reference_hash` oder `new_reference_hash` |
| `session.bot_signal_observed` | `telemetry_schema_version`, plus einen `bot_score` oder mindestens eine Telemetriemetrik |
| `responsible_gambling.self_exclusion_match` | `registry_source`, `exclusion_status`, `identity_match_ref` |

> [!WARNING]
>
> Senden Sie **Referenzen und Hashes**, niemals Klartext-Geheimnisse. Zahlungsinstrumente, Auszahlungsziele und Änderungen an der Kontosteuerung werden als gehashte Referenz gespeichert, die Sie senden. Senden Sie niemals eine Kartennummer, eine vollständige Auszahlungsadresse, einen Passwort-Hash oder ein MFA-Geheimnis.

### Beispiel: eine P2P-Abrechnung

```json theme={null}
{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}
```

### Beispiel: ein Chargeback

```json theme={null}
{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}
```

Lebenszyklen von Streitfällen sind append-only: Eine Korrektur ist ein neues `dispute`-Ereignis, niemals eine Änderung des ersten.

## Idempotenz

`event_id` ist pro Anwendung eindeutig und bildet den gesamten Idempotenzvertrag.

* **Gleiche `event_id`, gleicher Inhalt** liefert `200` mit `"idempotent_replay": true` und dem ursprünglich gespeicherten Ereignis. Sie können beliebig oft wiederholen.
* **Gleiche `event_id`, anderer Inhalt** liefert `409`. Sie haben eine ID versehentlich erneut verwendet.

## Batches

`POST /v3/events/batch/` nimmt bis zu **500 Ereignisse** an. Ein Batch ist konstruktionsbedingt teilweise erfolgreich: Ein fehlerhafter Seitenaufruf darf niemals den benachbarten Chargeback mit zum Scheitern bringen.

```json theme={null}
{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}
```

Die Antwort lautet `207 Multi-Status`, wenn etwas abgelehnt wurde, und `201 Created`, wenn alles übernommen wurde.

## Status

| Status | Bedeutung |
| - | - |
| `ACCEPTED` | Gespeichert. Keine Regel hat den Status verändert (dies ist die übliche Antwort für die meisten Ereignisse). |
| `APPROVED` | Eine Regel wurde ausgeführt, und der Score blieb unter Ihrem Prüfschwellenwert. |
| `IN_REVIEW` | Eine Regel hat den Score über den Prüfschwellenwert gehoben oder den Status direkt gesetzt. |
| `DECLINED` | Eine Regel hat das Ereignis abgelehnt. |

`correlation_pending: true` bedeutet, dass noch eine Regel, die mehrere Subjekte betrifft, ausgeführt werden muss. Dies geschieht innerhalb weniger Minuten, und Status und Score des Ereignisses werden im bestehenden Ereignis aktualisiert. Siehe [asynchrone Regeln](https://docs.didit.me/de/transaction-monitoring/event-rules.md#echtzeit--und-asynchrone-regeln).

## Aufbewahrung

Ereignisse fallen weit häufiger an als Transaktionen. Daher wird jedes Ereignis bei Eingang einer Aufbewahrungsklasse zugeordnet.

| Klasse | Standard-Aufbewahrung im Hot-Storage | Was hier landet |
| - | - | - |
| `low_value` | 14 Tage | Seitenaufrufe, Heartbeats, Gerätesichtungs-Pings, Bot-Telemetrie, Promotion-Aufrufe |
| `standard` | 30 Tage | Auth, Session, Gameplay, Bonus, Affiliate, Custom |
| `risk_relevant` | 90 Tage | Security- und Responsible-Gambling-Ereignisse sowie **jedes Ereignis, auf das eine Regel zugetroffen hat** |
| `monetary_or_compliance` | Transaktions-Aufbewahrung | Zahlungs- und Streitfallereignisse |

Aus der Tabelle folgen zwei Regeln:

* Ein Ereignis, auf das eine Regel zutrifft, ist ein Beweisstück und wird daher automatisch in `risk_relevant` hochgestuft.
* Zahlungs- und Streitfallereignisse behalten die Transaktions-Aufbewahrung. Sie laufen niemals nach dem Ereignis-Zeitplan ab, und die klassenspezifischen Überschreibungen können sie nicht verkürzen.

Überschreiben Sie die drei ablaufbaren Klassen pro Anwendung unter **Transactions → Settings → Event monitoring** (jeweils 1-730 Tage).

## IP-Anreicherung

Ereignisse enthalten dieselbe [IP-Anreicherung](https://docs.didit.me/de/transaction-monitoring/ip-enrichment.md) wie Transaktionen: Land, ASN sowie VPN-/Proxy- und Rechenzentrums-Kennzeichen. Die Anreicherung erfolgt **pro eindeutiger Adresse, niemals pro Ereignis**. Bei einer Sitzung mit 200 Seitenaufrufen von einer Adresse wird diese Adresse nur einmal aufgelöst.

Telemetrie mit niedrigem Wert geht noch weiter: Sie liest die Anreicherung nur, wenn ein anderes Ereignis diese Adresse bereits aufgelöst hat. Sie löst niemals eine eigene Abfrage aus.

`GET /v3/events/enrichment-metrics/` liefert das Ergebnis, und die Konsole zeigt dieselben Werte oberhalb der Ereignisliste an:

```json theme={null}
{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}
```

## Ereignisse auslesen

```bash theme={null}
curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"
```

Filter: `event_category`, `action_type`, `status`, `retention_class`, `subject_vendor_data`, `business_vendor_data`, `session_id`, `device_fingerprint`, `ip_address`, `game_id`, `round_id`, `affiliate_code`, `payment_reference_id`, `counterparty_vendor_data`, `matched_only`, `occurred_from`, `occurred_to`, `search`. Filter mit mehreren Werten wiederholen den Parameter (`?status=A&status=B`).

### Die Zeitleiste eines Subjekts

```bash theme={null}
curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"
```

Ein `vendor_data` ist nur **innerhalb** eines Entitätstyps eindeutig: Dieselbe ID kann sowohl einen Benutzer als auch ein Unternehmen bezeichnen, und Didit behandelt beide als zwei verschiedene Subjekte. Mit `entity_type` legen Sie fest, welches davon Sie abfragen: `individual` (Standard) oder `company`. Wenn Sie den Parameter bei einer Unternehmens-ID weglassen, wird die Zeitleiste der Person zurückgegeben, nicht beide. Dieselben Listenfilter gelten.

`GET /v3/events/{event_uuid}/` liefert zusätzlich das Payload, den Gerätekontext, die IP-Anreicherung, die zwischengespeicherten Risikosignale des Subjekts und jede Regelübereinstimmung mit ihrer Evidenz, einschließlich der Angabe, ob jedes übereinstimmende Feld serverseitig abgeleitet, vom SDK abgeleitet oder vom Kunden bereitgestellt wurde.

`DELETE /v3/events/{event_uuid}/delete/` löscht ein Ereignis. Es wird von keiner Abfrage mehr zurückgegeben, und die Löschung ist unwiderruflich.

## Weiter

> [card] [Regeln für Ereignisse](https://docs.didit.me/de/transaction-monitoring/event-rules.md)
>
> Geschwindigkeits-, Verhältnis-, Sequenz- und Korrelationsregeln für Ereignisdaten.

> [card] [Übermittlung von Ereignissen über das SDK](https://docs.didit.me/de/transaction-monitoring/sdk-event-submission.md)
>
> Ereignisse direkt auf dem Gerät mit eingeschränkten Zugangsdaten erfassen.


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