Designing Event Monitoring Rules That Stay Explainable

Explainable fraud decisions start with the event you send, not with the dashboard you open later. A rule engine can only produce useful evidence when every login, payment, signup, and account update carries stable identifiers and the metadata that rule actually reads.

Send customer, device, and session identifiers with every event. Naiza ties them to the decision and the matching rules, so support can see why an event went to review and engineering can find the event id on every ticket.

Send the same event the same way

Use consistent eventName values such as user.login or payment.completed. If one service says login and another says user.login, you will write two rules or none. Pick names, write them down, and refuse aliases.

Send customer, device, IP, session, and amount context on the first API call. Do not plan to "enrich later" for the decision you need now. customer.externalId should be the same id you use in your own user table. The device fingerprint should be the same handle you will later list. The session id should be the one support already has on the ticket.

Keep rule names human-readable. They appear in review workflows. login_failures_same_fingerprint_10m is a name an analyst can use. rule_14 is a name that will die in Slack.

Reserve BLOCK for high-confidence cases. Use REVIEW for signals that need human context: a new device, velocity near a threshold, a VPN on an unknown fingerprint. Scoring can rank those cases. Named rules decide. That is the same split as ALLOW, REVIEW, BLOCK without a black box.

{
  "eventName": "payment.completed",
  "customer": { "externalId": "user_123456" },
  "device": { "externalId": "device_abc123" },
  "ip": "203.0.113.42",
  "sessionId": "session_xyz789",
  "metadata": { "amount": 500, "currency": "SAR" }
}

This example connects customer, device, session, and amount context. The event monitoring guide provides the request fields and response handling for your integration.

Make the decision auditable

Store correlationIds.eventId beside your product transaction id. That gives support, risk, and engineering a shared key when a customer asks why a payment was reviewed. Without it, you are reconstructing the event from logs and hoping the timestamps line up.

The case note should be able to say three things: which event fired, which named rule matched, and which outcome you applied. ALLOW means the product proceeded. REVIEW means you added friction or queued a human. BLOCK means you stopped the action. If those words mean something else in your product, write the mapping down before go-live.

Start new rules in shadow or REVIEW. Watch a week of volume. Flash sales, shared mobile networks, and family tablets will all look like bursts. Tighten the rule before you enforce BLOCK. If you need the four-part shape of a countable rule, velocity checks that stay explainable is the companion note.

One event, one decision, one key

Do not send a payment and then invent a second synthetic event to "make the rule fire." Change the rule. Do not reuse a login event for a payout-detail change. The action is different and the analyst needs to see that.

When the first week is noisy, resist adding more signals. Look at the event you already send. Missing customer.externalId and a device fingerprint will produce worse decisions than any extra enrichment you bolt on later.

Send stable customer and device identifiers, use readable rule names, and store the returned event ID with the transaction.