Notification System

Fraudio's notification system delivers alerts for both screening and monitoring scenarios. These notifications can be received via webhook, providing real-time or scheduled alerts about suspicious activities, rule triggers, and risk assessments.

Webhook Configuration

Webhook configuration can be done on the subscription page (soon to be released) in the Fraudio portal. On the subscription page, you can choose the file type and delivery channel. Initially, the available channels are webhook and email.

When JSON is selected as the file type and webhook is selected as the delivery channel, your webhook will receive POST requests with the JSON payload format described below whenever new alerts are generated.

Notification Payload Format

The primary notification format is in JSON, ensuring compatibility and ease of integration with various systems. The schema is designed to be backward compatible, allowing for seamless updates and enhancements without disrupting existing integrations.

Schema Definition

The notification payload follows this JSON schema:

Field	Data Type	Description
id	String (UUID)	Unique identifier for the alert notification
tenant_slug	String	Identifier for the client tenant
tenant_api_mode	String	API mode environment (e.g., "production", "sandbox")
report_group_id	String (UUID)	Unique identifier for the report group this alert belongs to
scope	String	Type of alert. Possible values: "mif", "pfd", "aml"
reported_at	Double	Unix timestamp (in seconds) indicating when the alert was generated
reason_category	String	Category code and description of the alert reason
reason_title	String	Short, human-readable title describing why the alert was triggered
score	Double | null	Risk score (0.0 - 1.0), where higher values indicate greater risk
tags	Array of Strings	Array of relevant tags or categories associated with the alert
classification	Object	Risk assessment information Field Data Type Description recommendation String | null Recommended action level. Possible values: "yellow", "red", "black" priority String | null Priority level (lower numbers typically indicate higher priority)
amount	Double | null	Total monetary amount associated with the alert
currency	String | null	ISO 4217 currency code (numeric format, e.g., "978" for EUR)
subjects	Array of Objects	Array of entities involved in the alert Each subject object contains: Field Data Type Description type String Type of entity (e.g., "merchant", "cardholder", "cardtoken") id String Client-specific identifier for the subject entity name String Display name of the subject entity (may be "none" if not available)
rule	Object | null	Information about the rule that triggered the alert. Present only if a rule triggered the alert Field Data Type Description id String (UUID) Unique identifier for the triggered rule version Integer Version number of the rule
is_shadow	Boolean	Whether this is a shadow mode alert (not affecting production decisions)
transactions	Array of Strings	Array of transaction IDs related to this alert
source	String	Source of the alert. Possible values: "monitoring", "screening"

Rule Object Availability

The Rule object is only present when a rule has triggered the alert. Notifications can also be generated by other detection mechanisms (e.g., machine learning models, behavioral analysis) that do not involve specific rules.

Example Payload

{
  "id": "33726a5d-df85-47a3-b85e-a7eaac3bf26f",
  "tenant_slug": "clientslug",
  "tenant_api_mode": "production",
  "report_group_id": "3ae5903b-0182-dddd-ebab-654896d0ca6d",
  "scope": "mif",
  "reported_at": 1.764248476E9,
  "reason_category": "[C112] Frequent round number transactions - all verticals",
  "reason_title": "Alert if more than 10 round number transactions in 7 days on a single merchant",
  "score": 1.0,
  "tags": [
    "mif"
  ],
  "classification": {
    "recommendation": "yellow",
    "priority": "5"
  },
  "amount": 20706.19,
  "currency": "978",
  "subjects": [
    {
      "type": "merchant",
      "id": "lucca apartments and villas s.r.l.",
      "name": "none"
    }
  ],
  "rule": {
    "id": "2ef5bed0-32c7-4c74-b3ec-6d0c307a1489",
    "version": 3
  },
  "is_shadow": false,
  "transactions": [
    "59205449",
    "59205554",
    "59205556"
  ],
  "source": "monitoring"
}

Webhook Delivery

• Webhooks are sent via HTTP POST requests.
• The Content-Type header is set to application/json.
• Your endpoint should respond with a 2xx status code to acknowledge successful receipt.
• Fraudio will retry failed deliveries according to our retry policy.