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

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 ausgewertet, die auch Ihre Transaktionen bewertet.

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.

Aufbau des Envelopes

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

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

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`

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

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

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

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

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

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

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

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

Regeln für Ereignisse

Geschwindigkeits-, Verhältnis-, Sequenz- und Korrelationsregeln für Ereignisdaten.

Übermittlung von Ereignissen über das SDK

Ereignisse direkt auf dem Gerät mit eingeschränkten Zugangsdaten erfassen.

Erste Schritte

Funktionen

Referenz

Konsole

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

Endpoints

Aufbau des Envelopes

Kategorien

Pflicht-Payload-Schlüssel

Beispiel: eine P2P-Abrechnung

Beispiel: ein Chargeback

Idempotenz

Batches

Status

Aufbewahrung

IP-Anreicherung

Ereignisse auslesen

Die Zeitleiste eines Subjekts

Weiter

Regeln für Ereignisse

Übermittlung von Ereignissen über das SDK

​Endpoints

​Aufbau des Envelopes

​Kategorien

​Pflicht-Payload-Schlüssel

​Beispiel: eine P2P-Abrechnung

​Beispiel: ein Chargeback

​Idempotenz

​Batches

​Status

​Aufbewahrung

​IP-Anreicherung

​Ereignisse auslesen

​Die Zeitleiste eines Subjekts

​Weiter

Regeln für Ereignisse

Übermittlung von Ereignissen über das SDK

Endpoints

Aufbau des Envelopes

Kategorien

Pflicht-Payload-Schlüssel

Beispiel: eine P2P-Abrechnung

Beispiel: ein Chargeback

Idempotenz

Batches

Status

Aufbewahrung

IP-Anreicherung

Ereignisse auslesen

Die Zeitleiste eines Subjekts

Weiter