Event Monitoring

Model product events and turn rule outcomes into decisions.

Guides API Reference Code Examples Best Practices

Event Monitoring Integration

Use event monitoring when you want Naiza to evaluate product activity as it happens: signups, logins, payments, withdrawals, profile changes, and other actions that may carry fraud risk.

Send a normalized event to Naiza.
Naiza enriches and evaluates it against tenant rules.
Apply the returned ALLOW, BLOCK, or REVIEW decision.
Send feedback after operations confirms the outcome.

Choose the Integration Mode

Synchronous decisioning

Use POST /api/v1/decisions/evaluate when the product flow needs an immediate decision before it can continue.

POST /api/v1/decisions/evaluate

{
  "eventName": "payment.attempt",
  "eventCategory": "TRANSACTION",
  "customer": {
    "externalId": "cust_123",
    "email": "user@example.com"
  },
  "device": {
    "externalId": "device_abc123",
    "fingerprint": "fp_abc123"
  },
  "ip": "203.0.113.42",
  "sessionId": "session_xyz789",
  "metadata": {
    "amount": 250,
    "currency": "SAR",
    "paymentMethod": "card"
  }
}

Asynchronous monitoring

Use POST /api/v1/events or POST /api/v1/events/async when the product does not need to wait for a decision.

POST /api/v1/events/async

{
  "eventName": "user.login",
  "eventCategory": "AUTHENTICATION",
  "customer": { "externalId": "cust_123" },
  "device": { "externalId": "device_abc123" },
  "ip": "203.0.113.42",
  "country": "SA",
  "sessionId": "session_xyz789"
}

Model Events Consistently

Keep event names stable and domain-specific, such as user.signup, payment.attempt, or withdrawal.requested.

customer.externalId - your stable customer identifier.
device.externalId or device.fingerprint - stable device context.
sessionId - groups activity from one visit.
metadata - product-specific fields rules can evaluate.

Rules to Decisions

Rules evaluate the event payload and produce an action. Use high confidence fraud signals for BLOCK, ambiguous signals for REVIEW, and normal activity for ALLOW.

Keep rule names human-readable because they appear in operational review and feedback workflows.

Handle Follow-Up

Store response identifiers from synchronous decisions and use correlationIds.eventId when querying an event or sending feedback.

{
  "decision": "REVIEW",
  "riskScore": 82,
  "correlationIds": {
    "requestId": "req_abc123xyz",
    "eventId": "evt_ckm9876543210"
  }
}

POST /api/v1/feedback/event/:id

{
  "label": "FRAUD",
  "notes": "Customer confirmed the payment was unauthorized",
  "externalCaseId": "case_12345"
}

Event Monitoring