---
title: "Event Monitoring Integration"
description: "Model product events and turn rule outcomes into decisions."
collection: "guides"
slug: "event-monitoring"
url: "https://naiza.ai/docs/guides/event-monitoring"
markdown: "https://naiza.ai/docs/guides/event-monitoring.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Event Monitoring Integration

> Model product events and turn rule outcomes into decisions.

## Table of contents

- [Choose the Integration Mode](#choose-the-integration-mode)
  - [Synchronous decisioning](#synchronous-decisioning)
  - [Asynchronous monitoring](#asynchronous-monitoring)
- [Model Events Consistently](#model-events-consistently)
- [Rules to Decisions](#rules-to-decisions)
- [Handle Follow-Up](#handle-follow-up)
- [Go-Live Checklist](#go-live-checklist)

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. The integration flow is:

1. Send a normalized event to Naiza.
2. Naiza enriches and evaluates the event against tenant rules.
3. Your application applies the returned `ALLOW`, `BLOCK`, or `REVIEW`
   decision.
4. Your operations team reviews queued cases and sends feedback when outcomes
   are confirmed.

See the [Events API](https://naiza.ai/docs/api-reference/events.md), [Decisions API](https://naiza.ai/docs/api-reference/decisions.md),
and [Feedback API](https://naiza.ai/docs/api-reference/feedback.md) references for endpoint-level
contracts.

## Choose the Integration Mode

### Synchronous decisioning

Use `POST /api/v1/decisions/evaluate` when the product flow needs an immediate
decision before it can continue, such as approving a payment or blocking a risky
account update.

```http
POST /api/v1/decisions/evaluate
```

```json
{
  "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"
  }
}
```

Use the response decision immediately:

- `ALLOW` - continue the product flow.
- `BLOCK` - stop the action and show the appropriate product state.
- `REVIEW` - add friction, hold the action, or queue manual review.

### Asynchronous monitoring

Use `POST /api/v1/events` or `POST /api/v1/events/async` when the product does
not need to wait for a decision. This is useful for analytics enrichment,
portfolio monitoring, and background review queues.

```http
POST /api/v1/events/async
```

```json
{
  "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. Examples:

- `user.signup`
- `user.login`
- `payment.attempt`
- `payment.completed`
- `withdrawal.requested`
- `profile.email_changed`

Send the same identifiers on every event:

- `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. A typical policy is:

1. High-confidence fraud signals return `BLOCK`.
2. Suspicious but ambiguous signals return `REVIEW`.
3. Normal activity returns `ALLOW`.

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

## Handle Follow-Up

Store the response identifiers from synchronous decisions:

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

Use `correlationIds.eventId` when querying the event or sending feedback after
an investigation.

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

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

## Go-Live Checklist

- Map every critical product action to an event name.
- Confirm required fields are present in staging.
- Create initial rules for `ALLOW`, `BLOCK`, and `REVIEW` outcomes.
- Decide whether each flow should call synchronous decisioning or async ingest.
- Store correlation IDs in your logs.
- Wire feedback from operations back into Naiza.

## Related documentation

- [Overview](https://naiza.ai/docs/guides/overview.md) — Base URL, authentication, decision types, risk scores, and rate limits.
- [Getting Started](https://naiza.ai/docs/guides/getting-started.md) — Make your first Naiza API call and verify your integration.
- [Tenant Onboarding](https://naiza.ai/docs/guides/tenant-onboarding.md) — Create tenants, invite operators, and configure webhooks.
- [Web SDK — Install & CDN](https://naiza.ai/docs/guides/web-sdk-install.md) — Install the browser SDK via CDN, self-host, and verify ingest.
- [Quick Start](https://naiza.ai/docs/guides/quick-start.md) — Common operations for events, decisions, lists, and feedback.
- [AML Integration](https://naiza.ai/docs/guides/aml-integration.md) — Screen customers and counterparties against AML watchlists.
- [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) — Node.js, Python, cURL, and webhook handler examples.
- [Best Practices](https://naiza.ai/docs/guides/best-practices.md) — Production guidance for keys, idempotency, and enforcement.

---

*Source: [https://naiza.ai/docs/guides/event-monitoring](https://naiza.ai/docs/guides/event-monitoring) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*