> ## 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.
# 创建监控事件 API
> 从后端向 Didit 发送一次登录、游戏、奖金、支付、争议或安全事件，由 Didit 存储、富化，并依据您的事件规则进行评分。
创建监控事件 API 提示词
将提示词复制到剪贴板
\
\`Send one non-monetary monitoring event (login, session, gameplay, bonus, affiliate, payment, dispute, security, responsible gambling or custom) from my backend to Didit.
Endpoint:
POST https://verification.didit.me/v3/events/
Authentication:
Use the x-api-key header with my Didit API key, from my backend only. A scoped key needs transactions: write.
Goal:
\- Record what happened on my platform so Didit's event rules can score it alongside my transactions, and read the verdict from the response.
Request body (application/json):
\{
"event_id": "login-2026-10-17-000001", // required - my id, unique per application, the idempotency key (max 128)
"event_category": "auth", // required - auth, session, gameplay, bonus, affiliate, payment, dispute, security, responsible_gambling, custom
"action_type": "login", // required - what happened inside the category (max 128)
"occurred_at": "2026-10-17T09:15:02.481Z", // required - at most 7 days in the past, 5 minutes in the future
"subject": { "vendor_data": "user-42", "entity_type": "individual" }, // required - entity_type individual (default) or company
"session": { "session_id": "web-session-abc", "sequence": 142 },
"device_context": { "fingerprint": "didit-fp-v2:a8c1", "network_context": { "ip_address": "203.0.113.42" } },
"transaction_context": { "amount": "1000.00", "currency": "EUR", "payment_reference_id": "dep_735" },
"payload": { "method": "password" }, // category fields, max 16 KB
"custom_values": { "vip_tier": "gold" } // max 100 scalar keys
}
Behavior:
\- Validated, stored, IP-enriched and evaluated by the real-time event rules before the response returns. Cross-subject and long-window rules run asynchronously within minutes (correlation_pending: true).
\- Some actions require payload keys, for example gameplay.p2p_settlement (game_id, counterparty_vendor_data, stake_amount, net_result_amount, role, and one of hand_id, round_id, match_id), payment.deposit_completed (payment_reference_id, amount, currency, payment_method, status) and dispute.chargeback_opened (payment_reference_id and one of dispute_id, chargeback_id). transaction_context keys count towards these requirements.
\- Send hashes and references, never a card number, a full withdrawal address, a password hash or an MFA secret.
\- Idempotency: the same event_id with the same event_category, action_type, occurred_at, subject.vendor_data and payload returns 200 with idempotent_replay true and the stored event's result. Different values in those fields return 409; the other fields are not compared. Retry safely on timeouts.
\- The IP address used for enrichment and rules is device_context.network_context.ip_address as you send it.
\- In a sandbox application no rules run: status is ACCEPTED and rules_evaluated_count is 0.
\- The subject resolves to the user (or company) with that vendor_data; one is created when none exists.
\- Event ingestion is opt-in: until it is switched on in Transactions > Settings > Event monitoring, this call returns 403 with code event_monitoring_disabled and stores nothing.
Example call:
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-10-17-000001","event_category":"auth","action_type":"login","occurred_at":"2026-10-17T09:15:02.481Z","subject":{"vendor_data":"user-42"},"device_context":{"network_context":{"ip_address":"203.0.113.42"}},"payload":{"method":"password"}}'
What to read from the response:
\- event_uuid - Didit id of the stored event.
\- status - ACCEPTED (stored, no rule changed it), APPROVED, IN_REVIEW or DECLINED.
\- score, rules_evaluated_count, rules_matched_count, rule_matches[] (rule_id, library_key, mode, is_async).
\- correlation_pending - when true, read GET /v3/events/{event_uuid}/ later for the final status.
\- retention_class and expires_at (null for payment and dispute events).
\- idempotent_replay - true when the event was already stored.
Failure modes:
\- 400 - validation error keyed by field (missing field, occurred_at outside the window, payload over 16 KB, nested custom_values, missing required payload keys).
\- 401 - the API key has expired.
\- 403 - missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write, or code event_monitoring_disabled.
\- 409 - event_id reused with different content; use a new event_id.
\- 429 - more than 600 ingestion requests per minute for this API key (event and transaction ingestion share this budget, apart from the 300 of every other write); honor Retry-After.
Side effects: stores the event, may create the subject's user or company, and applies the actions of matched active rules (score, status, tags, notes, list entries, cases).
For the full integration shape, see /integration/integration-prompt.`
\
粘贴到
> [!NOTE]
>
> 事件接收需要主动开启。发送事件前，请先在 **Transactions > Settings > Event monitoring** 中开启此功能。在开启之前，该端点会返回 `403`，并附带 `"code": "event_monitoring_disabled"`。[事件接收](https://docs.didit.me/zh/transaction-monitoring/events.md)介绍事件封装、十类事件、必需的 payload 键以及数据保留类别。[事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)说明哪些规则在请求中运行，哪些规则异步运行。如果要从浏览器或应用发送事件，而不是从后端发送，请使用 [SDK 事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission.md)。
## OpenAPI
````yaml zh/openapi-25.json POST /v3/events/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/events/:
post:
tags:
- Monitoring Events
summary: 创建监控事件
description: >-
从您的后端发送一个非货币事件（登录、会话、游戏活动、奖金、联盟、支付、争议、安全、负责任博彩或自定义）。在返回响应之前，系统会根据其类别约定对该事件进行验证、存储、针对每个唯一的公网
IP 地址进行一次 IP 信息补充，并由您的实时事件规则进行评估；跨主体和长窗口规则以异步方式运行（`correlation_pending:
true`），而在沙盒应用中不运行任何规则。`event_id` 为幂等性密钥：相同的 `event_id` 搭配相同的
`event_category`、`action_type`、`occurred_at`、`subject.vendor_data` 和
`payload` 将返回 `200`，且包含 `idempotent_replay: true`
以及已存储的结果（不会比较其他外层字段），而不同的值将返回 `409`。事件摄取按应用选择开启：在开启之前，此 endpoint 将返回
`403` 及 `code: event_monitoring_disabled` 且不存储任何内容。带作用域的 API 密钥需要
`transactions: write`
权限。请参阅[事件摄取](https://docs.didit.me/zh/transaction-monitoring/events)和[事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules)；如需从浏览器或应用发送事件，请使用[SDK
事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission)。
operationId: create_monitoring_event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventCreateRequest'
examples:
Login:
value:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
Deposit completed:
value:
event_id: deposit-2026-10-17-000002
event_category: payment
action_type: deposit_completed
occurred_at: '2026-10-17T09:16:40Z'
subject:
vendor_data: user-42
transaction_context:
amount: '100.00'
currency: EUR
direction: inbound
payment_reference_id: dep_736
payload:
payment_method: card
status: completed
Chargeback opened:
value:
event_id: chargeback-2026-10-16-000318
event_category: dispute
action_type: chargeback_opened
occurred_at: '2026-10-16T14:02:11Z'
subject:
vendor_data: user-42
payload:
payment_reference_id: dep_735
chargeback_id: cb_5521
amount: '250.00'
currency: EUR
reason_code: fraud
responses:
'200':
description: 幂等重放：具有此 `event_id` 且内容相同的事件已被存储。未重新存储或评估任何内容；响应体描述已存储的事件。
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Replay:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: true
rule_matches: []
'201':
description: 事件已存储并完成评估。
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Stored, no rule matched:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: false
rule_matches: []
Rule matched, async rule pending:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: IN_REVIEW
score: 40
rules_evaluated_count: 6
rules_matched_count: 1
correlation_pending: true
retention_class: risk_relevant
expires_at: '2027-01-15T09:15:02.481000Z'
idempotent_replay: false
rule_matches:
- rule_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
library_key: null
mode: ACTIVE
is_async: false
'400':
description: 验证失败。响应体以字段为键；嵌套字段为嵌套对象。未存储任何内容。
content:
application/json:
examples:
Missing fields:
value:
event_id:
- This field is required.
subject:
- This field is required.
Unknown category:
value:
event_category:
- '"login" is not a valid choice.'
occurred_at too old:
value:
occurred_at:
- >-
occurred_at is more than 7 days in the past. Use the
batch import lane for backfills.
occurred_at in the future:
value:
occurred_at:
- occurred_at is more than 5 minutes in the future.
Missing subject vendor_data:
value:
subject:
vendor_data:
- This field is required.
Missing required payload keys:
value:
payload:
- >-
payment.deposit_completed requires: payment_method,
status.
Missing one-of payload key:
value:
payload:
- >-
dispute.chargeback_opened requires one of: dispute_id,
chargeback_id.
Security change without changed_field:
value:
payload:
- security.*_changed requires 'changed_field'.
Payload too large:
value:
payload:
- >-
payload exceeds 16384 bytes. Summarise telemetry
client-side.
Too many custom_values:
value:
custom_values:
- custom_values accepts at most 100 keys.
Nested custom value:
value:
custom_values:
- >-
custom_values['limits'] must be a scalar - rule
conditions cannot address nested values.
'401':
description: 作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。
content:
application/json:
examples:
Expired key:
value:
detail: This API key has expired.
'403':
description: >-
缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: write`
权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP
白名单之外的请求。在应用关闭事件摄取时也会返回 `code:
event_monitoring_disabled`；在此情况下不会存储任何内容，且该检查在验证请求体之前运行。
content:
application/json:
examples:
Event monitoring disabled:
value:
detail: >-
Event monitoring is not enabled for this application. Turn
on event ingestion in the transaction monitoring settings
before submitting events.
code: event_monitoring_disabled
Missing or invalid API key:
value:
detail: You do not have permission to perform this action.
Scoped key without access:
value:
detail: This API key has no write access to transactions.
Key limited to workflows or approved sessions:
value:
detail: >-
This API key only reaches sessions inside its workflow or
status limits, so it can't use this endpoint.
IP not allowed:
value:
detail: This API key can't be used from this IP address.
'409':
description: >-
`event_id` 已用于具有不同内容的事件（类别、操作类型、`occurred_at`、主体 `vendor_data` 或
payload）。请使用新的 `event_id` 发送该事件。
content:
application/json:
examples:
event_id reused:
value:
event_id: >-
event_id 'login-2026-10-17-000001' already exists with a
different payload.
'429':
description: >-
超出速率限制：交易创建和事件摄入（`POST /v3/transactions/`、`POST /v3/events/`、`POST
/v3/events/batch/`）共享每个 API 密钥每分钟 600 次请求的配额，独立于所有其他写入请求共享的 300
次配额。请等待 `Retry-After` 秒，然后重试。
headers:
Retry-After:
description: 重试前需等待的秒数，向上取整以确保重试落在下一个时间窗口内。
schema:
type: integer
minimum: 1
example: 30
content:
application/json:
examples:
Throttled:
value:
detail: >-
Ingestion rate limit exceeded. You can make up to 600
requests per minute.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
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-10-17-000001",
"event_category": "auth",
"action_type": "login",
"occurred_at": "2026-10-17T09:15:02.481Z",
"subject": {"vendor_data": "user-42", "entity_type": "individual"},
"session": {"session_id": "web-session-abc", "sequence": 142},
"device_context": {
"fingerprint": "fp-a8c1",
"network_context": {"ip_address": "203.0.113.42"}
},
"payload": {"method": "password"}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.monitoring_events.create(
event_id="login-2026-10-17-000001",
event_category="auth",
action_type="login",
occurred_at="2026-10-17T09:15:02.481Z",
time_zone="Europe/Madrid",
subject={
"vendor_data": "user-42",
"entity_type": "individual",
},
session={
"session_id": "web-session-abc",
"sequence": 142,
},
device_context={
"fingerprint": "fp-a8c1",
"network_context": {
"ip_address": "203.0.113.42",
},
},
payload={"method": "password"},
custom_values={"vip_tier": "gold"},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.monitoringEvents.create({
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" },
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.time.OffsetDateTime;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.MonitoringEventCreateRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.monitoringEvents().create(MonitoringEventCreateRequest.builder()
.eventId("login-2026-10-17-000001")
.eventCategory(MonitoringEventCreateRequest.EventCategory.of("auth"))
.actionType("login")
.occurredAt(OffsetDateTime.parse("2026-10-17T09:15:02.481Z"))
.timeZone("Europe/Madrid")
.subject(MonitoringEventCreateRequest.Subject.builder()
.vendorData("user-42")
.entityType("individual")
.build())
.session(MonitoringEventCreateRequest.Session.builder()
.sessionId("web-session-abc")
.sequence(142L)
.build())
.deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()
.fingerprint("fp-a8c1")
.networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()
.ipAddress("203.0.113.42")
.build())
.build())
.payload(Map.of("method", "password"))
.customValues(Map.of("vip_tier", MonitoringEventCreateRequest.CustomValuesValue.ofString("gold")))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
monitoringEvents->create([
'event_id' => 'login-2026-10-17-000001',
'event_category' => 'auth',
'action_type' => 'login',
'occurred_at' => '2026-10-17T09:15:02.481Z',
'time_zone' => 'Europe/Madrid',
'subject' => [
'vendor_data' => 'user-42',
'entity_type' => 'individual',
],
'session' => [
'session_id' => 'web-session-abc',
'sequence' => 142,
],
'device_context' => [
'fingerprint' => 'fp-a8c1',
'network_context' => [
'ip_address' => '203.0.113.42',
],
],
'payload' => ['method' => 'password'],
'custom_values' => ['vip_tier' => 'gold'],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.monitoring_events.create(
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" }
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.MonitoringEvents.CreateAsync(new
MonitoringEventCreateRequest
{
EventId = "login-2026-10-17-000001",
EventCategory = "auth",
ActionType = "login",
OccurredAt = DateTimeOffset.Parse("2026-10-17T09:15:02.481Z"),
TimeZone = "Europe/Madrid",
Subject = new()
{
VendorData = "user-42",
EntityType = "individual",
},
Session = new MonitoringEventCreateRequestSession
{
SessionId = "web-session-abc",
Sequence = 142,
},
DeviceContext = new MonitoringEventCreateRequestDeviceContext
{
Fingerprint = "fp-a8c1",
NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext
{
IpAddress = "203.0.113.42",
},
},
Payload = new Dictionary { ["method"] = "password" },
CustomValues = new Dictionary { ["vip_tier"] = "gold" },
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
MonitoringEventCreateRequest:
type: object
description: >-
事件信封，每个类别均相同。支持 camelCase 别名：`eventId`、`eventCategory`（或
`category`）、`actionType`、`occurredAt`、`timeZone`（或
`zoneId`）、`deviceContext`（或
`device`）、`transactionContext`、`customValues`（或 `props`）；在 `subject`
内支持：`vendorData`、`entityType`、`fullName`；在 `session`
内支持：`sessionId`、`pageUrl`；在 `transaction_context`
内支持：`paymentReferenceId`。
required:
- event_id
- event_category
- action_type
- occurred_at
- subject
properties:
event_id:
type: string
maxLength: 128
description: >-
您对事件的标识符，在每个应用中唯一。它是幂等性密钥：在其下重新发送相同的
`event_category`、`action_type`、`occurred_at`、`subject.vendor_data` 和
`payload` 将被视为重放，任何不同则会导致冲突。
example: login-2026-10-17-000001
event_category:
type: string
enum:
- auth
- session
- gameplay
- bonus
- affiliate
- payment
- dispute
- security
- responsible_gambling
- custom
description: 事件类别。
example: auth
action_type:
type: string
minLength: 1
maxLength: 128
description: >-
该类别中发生的情况。开放词汇；[事件摄入](https://docs.didit.me/zh/transaction-monitoring/events)中列出的托管操作（例如
`login`、`deposit_completed`、`chargeback_opened`）会启用类型化验证和托管规则字段。首尾空格会被去除。
example: login
occurred_at:
type: string
format: date-time
description: 事件在您方发生的时间，ISO 8601 格式（无偏移量的值视为 UTC）。不能早于过去 7 天，也不能晚于未来 5 分钟。
example: '2026-10-17T09:15:02.481Z'
time_zone:
type: string
nullable: true
maxLength: 64
description: 您所在一侧事件发生时的时区，例如 `Europe/Madrid`。与事件一同存储；读取 endpoint 不会返回。
subject:
type: object
description: 事件所属的用户或公司。它会解析为您的应用中具有此 `vendor_data` 的用户（或公司）；若不存在则会创建一个。
required:
- vendor_data
properties:
vendor_data:
type: string
minLength: 1
maxLength: 255
description: 您对主体的 ID。
example: user-42
entity_type:
type: string
maxLength: 32
default: individual
description: >-
`company` 将主体解析为企业；任何其他值（默认 `individual`）将其解析为个人。同一个
`vendor_data` 可以分别指代一个企业和一个个人。
example: individual
full_name:
type: string
nullable: true
maxLength: 512
description: 显示名称，仅在此事件创建用户或企业时使用。
email:
type: string
format: email
nullable: true
description: 已验证为邮箱地址；不会存储在事件中。
phone:
type: string
nullable: true
maxLength: 32
description: 已验证；不会存储在事件中。
country:
type: string
nullable: true
maxLength: 3
description: 已验证；不会存储在事件中。
business:
type: object
description: 事件所属的企业（当与主体不同时）。仅读取 `vendor_data`。
additionalProperties: true
properties:
vendor_data:
type: string
maxLength: 255
description: 您对企业的 ID。可作为 `business_vendor_data` 进行过滤。
example: merchant-7
session:
type: object
description: 您针对该事件的会话上下文。
properties:
session_id:
type: string
nullable: true
maxLength: 255
description: 您的会话标识符。可作为 `session_id` 进行过滤和返回。
sequence:
type: integer
nullable: true
description: 事件在会话中的位置。以 `session_sequence` 返回。
page_url:
type: string
nullable: true
maxLength: 2048
description: 已验证；不会存储在事件中。
referrer:
type: string
nullable: true
maxLength: 2048
description: 已验证；不会存储在事件中。
device_context:
type: object
additionalProperties: true
description: >-
设备与网络上下文，按发送原样存储并通过 `GET /v3/events/{event_uuid}/` 返回。在此服务器通道上，Didit
无法看到终端用户的连接，因此规则进行丰富并使用的 IP 是您发送的 `network_context.ip_address`。
properties:
fingerprint:
type: string
maxLength: 255
description: 设备指纹。可通过 `device_fingerprint` 进行过滤。
persistent_device_id:
type: string
maxLength: 255
description: 您的持久化设备标识符。
bot_score:
type: integer
description: 来自您自有检测的机器人评分，为整数。
network_context:
type: object
additionalProperties: true
properties:
ip_address:
type: string
maxLength: 64
description: 终端用户的地址。公网地址按每个唯一地址丰富化一次。
example: 203.0.113.42
transaction_context:
type: object
description: 金额上下文。此处的非空值也会满足操作所需的 payload 键。
properties:
amount:
type: string
nullable: true
description: 以十进制字符串表示的金额（亦可接受数字）。
example: '1000.00'
currency:
type: string
nullable: true
maxLength: 10
description: 货币代码。
direction:
type: string
nullable: true
maxLength: 16
description: 资金流动方向，例如 `inbound` 或 `outbound`。
payment_reference_id:
type: string
nullable: true
maxLength: 255
description: 您的付款参考编号。可作为 `payment_reference_id` 进行过滤。
payload:
type: object
additionalProperties: true
description: >-
类别的领域字段，JSON 编码后最多 16384 字节。部分操作需要指定键（在 `payload` 或
`transaction_context` 中）：`gameplay.p2p_settlement` 需要
`game_id`、`counterparty_vendor_data`、`stake_amount`、`net_result_amount`、`role`
以及 `hand_id`、`round_id`、`match_id` 之一；`gameplay.bet_placed` 和
`gameplay.bet_settled` 需要
`game_id`；`payment.deposit_initiated`、`payment.deposit_completed`、`payment.withdrawal_requested`
和 `payment.withdrawal_completed` 需要
`payment_reference_id`、`amount`、`currency`、`payment_method`、`status`；`payment.withdrawal_address_changed`
需要
`withdrawal_address_hash`；`dispute.chargeback_opened`、`dispute.chargeback_won`
和 `dispute.chargeback_lost` 需要 `payment_reference_id` 以及
`dispute_id`、`chargeback_id` 之一；`session.bot_signal_observed` 需要
`telemetry_schema_version` 以及
`bot_score`、`actions_per_minute`、`timing_variance_ms`、`pointer_entropy`、`keystroke_entropy`、`reaction_time_ms_p50`
之一；`responsible_gambling.self_exclusion_match` 需要
`registry_source`、`exclusion_status`、`identity_match_ref`。以
`_changed` 结尾的每个 `security` 操作都需要 `changed_field`，并且当字段为
`password`、`mfa_method`、`mfa`、`email`、`phone`、`withdrawal_address`、`payout_method`
或 `api_key` 时，还需要 `previous_reference_hash` 或
`new_reference_hash`。请发送哈希和引用，切勿发送卡号、完整提现地址、密码哈希或 MFA 密钥。
custom_values:
type: object
description: >-
最多 100 个自定义键，可在规则中通过 `custom_values.` 寻址。值必须为标量（字符串、数字、布尔值或
null）；不支持嵌套对象和数组。
additionalProperties:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
example:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
MonitoringEventIngestResult:
type: object
description: 接收单个事件的结果。新事件与幂等重放返回相同的结构。
required:
- event_uuid
- event_id
- status
- score
- rules_evaluated_count
- rules_matched_count
- correlation_pending
- retention_class
- expires_at
- idempotent_replay
- rule_matches
properties:
event_uuid:
type: string
format: uuid
description: 已存储事件的 Didit 标识符。
event_id:
type: string
description: 您的 `event_id`。
status:
type: string
enum:
- ACCEPTED
- APPROVED
- IN_REVIEW
- DECLINED
description: 实时规则运行后的状态。请参阅 `MonitoringEvent.status`。
score:
type: integer
description: 实时规则运行后的分数。
rules_evaluated_count:
type: integer
minimum: 0
description: 请求中评估的事件规则数量。沙盒应用中为 0，因为沙盒中不运行规则。
rules_matched_count:
type: integer
minimum: 0
description: 匹配的规则数量，包括处于 `TEST` 模式的规则。
correlation_pending:
type: boolean
description: >-
当异步规则仍需运行时为 `true`。请在几分钟后调用 `GET /v3/events/{event_uuid}/` 以获取最终的
`status` 和 `score`。
retention_class:
type: string
enum:
- low_value
- standard
- risk_relevant
- monetary_or_compliance
description: 数据保留类别（在由命中规则提升后）。
expires_at:
type: string
format: date-time
nullable: true
description: 事件根据其保留类别到期并被删除的时间。对于 `monetary_or_compliance`（支付和争议）事件为 Null。
idempotent_replay:
type: boolean
description: 当具有此 `event_id` 且内容相同的事件已被存储时为 `true`；返回的值为已存储事件的值，且不会再次运行任何规则。
rule_matches:
type: array
description: 匹配该事件的规则。
items:
type: object
required:
- rule_id
- library_key
- mode
- is_async
properties:
rule_id:
type: string
format: uuid
description: 规则的 UUID。
library_key:
type: string
nullable: true
description: 规则从规则库安装时的库密钥，否则为 null。
mode:
type: string
enum:
- ACTIVE
- TEST
description: '`TEST` 规则会记录匹配，但不应用任何操作。'
is_async:
type: boolean
description: 当比对结果来自异步轮次时为 `true`。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
您的应用 API 密钥，可在 Business Console 的“开发者 -> API
密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
https://docs.didit.me/console/api-keys。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.