Alerts

Alerts are notifications generated by the antifraud system when anomalies or suspicious patterns are detected. The system consists of two parts: Alert Validators (rules that trigger alerts) and External Notifies (channels for sending notifications).

Overview

You can configure alerts:

In the Admin Panel: Settings → Alert Validators
Via API: Alert Validators endpoints

Alert Validator Types

Type	Description	Parameters
`TRANSACTION_CONVERSION`	Triggers when conversion rate reaches threshold	`optPercent`, `optMinCount`, `optOperatorOne`
`TRANSACTION_COUNT`	Triggers when transaction count reaches threshold	`optCount`, `optOperatorOne`
`TRANSACTION_MINUS_COUNT`	Triggers on declined/failed transactions	`optPercent`, `optCount`, `optOperatorOne`
`TRANSACTION_MINUS_COUNT_PREV_PERIOD`	Compares with previous periods	`optCount`, `optOperatorOne`, `optPeriodCount`
`LINK_DETECT_COUNT`	Triggers when linked customers are detected	`optCount`, `optOperatorOne`

Alert Levels

Each alert has a severity level:

Level	Description
`INFO`	Informational alert, no immediate action required
`WARN`	Warning, should be reviewed
`CRITICAL`	Critical alert, requires immediate attention

Configuration Parameters

Time Settings

Parameter	Type	Description	Example
`workerIntervalSec`	integer	How often the validator checks for conditions (seconds)	`60` (every minute)
`dataPeriodSec`	integer	Time window for data analysis (seconds)	`600` (last 10 minutes)
`retentionPeriodSec`	integer	How long to keep alerts before auto-deletion	`2592000` (30 days)

Threshold Parameters

Parameter	Type	Description	Example
`optCount`	integer	Threshold count	`100`
`optPercent`	integer	Threshold percentage (0-100)	`80`
`optMinCount`	integer	Minimum count for percentage calculation	`200`
`optPeriodCount`	integer	Number of previous periods to compare	`4`

Comparison Operators

Operator	Description
`GT`	Greater than
`GTE`	Greater than or equal
`LT`	Less than
`LTE`	Less than or equal

Grouping

Alert validators can group data for more granular analysis:

Group Order One (primary grouping):

Value	Description
`MERCHANT`	Group by merchant
`CASCADE`	Group by cascade
`GATE`	Group by gate

Group Order Two (secondary grouping):

Value	Description
`BIN`	Group by card BIN
`COUNTRY`	Group by country

Example: Setting groupOrderOne: "GATE" and groupOrderTwo: "COUNTRY" will create separate alerts for each gate+country combination.

Targets

Alert validators can be scoped to specific entities:

Target	Description
`cascadeIdList`	Monitor specific cascades
`gateIdList`	Monitor specific gates
`merchantIdList`	Monitor specific merchants
`binValueList`	Monitor specific card BINs
`countryCodeList`	Monitor specific countries

If no targets are specified, the validator monitors all entities.

Config List (Multiple Thresholds)

A single alert validator can have multiple configurations with different thresholds and levels. This allows creating tiered alerts:

{
  "configList": [
    {
      "level": "INFO",
      "workerIntervalSec": 60,
      "dataPeriodSec": 600,
      "optCount": 50,
      "optOperatorOne": "GTE"
    },
    {
      "level": "WARN",
      "workerIntervalSec": 60,
      "dataPeriodSec": 600,
      "optCount": 100,
      "optOperatorOne": "GTE"
    },
    {
      "level": "CRITICAL",
      "workerIntervalSec": 60,
      "dataPeriodSec": 600,
      "optCount": 200,
      "optOperatorOne": "GTE"
    }
  ]
}

Alert Validators API

Base URL: https://api.embermind.ch/api/v1/client/alert-validators

Get Validator Types

Get list of all validator types with their default parameters.

curl -X GET 'https://api.embermind.ch/api/v1/client/alert-validators/type-list' \
  -H 'x-api-key: YOUR_API_KEY'

Get Validator List

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "searchValue": "my validator",
    "merchantIdList": ["merchant-uuid"]
  }'

Get One Validator

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertValidatorId": "validator-uuid"
  }'

Create Validator

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "High transaction count alert",
    "type": "TRANSACTION_COUNT",
    "groupOrderOne": "GATE",
    "retentionPeriodSec": 2592000,
    "externalNotifyIdList": ["notify-uuid"],
    "cascadeIdList": [],
    "gateIdList": ["gate-uuid-1", "gate-uuid-2"],
    "merchantIdList": [],
    "binValueList": [],
    "countryCodeList": [],
    "configList": [
      {
        "level": "WARN",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 100,
        "optOperatorOne": "GTE"
      }
    ]
  }'

Update Validator

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertValidatorId": "validator-uuid",
    "title": "Updated title",
    "isActive": true,
    "configList": [
      {
        "level": "CRITICAL",
        "workerIntervalSec": 60,
        "dataPeriodSec": 300,
        "optCount": 50,
        "optOperatorOne": "GTE"
      }
    ],
    "externalNotifyIdList": ["notify-uuid"],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "binValueList": [],
    "countryCodeList": []
  }'

Toggle Active

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/toggle-active' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertValidatorId": "validator-uuid",
    "isActive": false
  }'

Remove Validator

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertValidatorId": "validator-uuid"
  }'

External Notifications

External notifications allow sending alerts to external systems via Email, Telegram, or Webhook.

Notification Types

Type	Description	Required Parameters
`EMAIL`	Send alerts via SMTP email	SMTP settings + target emails
`TG`	Send alerts to Telegram	Bot token + chat IDs
`WEBHOOK`	Send alerts to HTTP endpoint	URL + method + headers

External Notifies API

Base URL: https://api.embermind.ch/api/v1/client/external-notifies

Get Types

curl -X GET 'https://api.embermind.ch/api/v1/client/external-notifies/type-list' \
  -H 'x-api-key: YOUR_API_KEY'

Get List

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Get One

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalNotifyId": "notify-uuid"
  }'

Create Email Notification

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Email alerts",
    "type": "EMAIL",
    "optSmtpHost": "smtp.gmail.com",
    "optSmtpPort": "587",
    "optSmtpEmail": "[email protected]",
    "optSmtpPassword": "app-password",
    "optSmtpIsSecure": true,
    "optSmtpTargetEmailList": ["[email protected]", "[email protected]"]
  }'

Create Telegram Notification

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Telegram alerts",
    "type": "TG",
    "optTgBotUsername": "MyAlertBot",
    "optTgBotToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "optTgBotChatIdList": ["-1001234567890", "-1009876543210"]
  }'

Create Webhook Notification

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Webhook alerts",
    "type": "WEBHOOK",
    "optApiUrl": "https://api.company.com/webhooks/alerts",
    "optApiMethod": "POST",
    "optApiHeaders": {
      "Authorization": "Bearer secret-token",
      "Content-Type": "application/json"
    }
  }'

Update External Notify

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalNotifyId": "notify-uuid",
    "title": "Updated title",
    "isActive": true,
    "optSmtpTargetEmailList": ["[email protected]"]
  }'

Toggle Active

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/toggle-active' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalNotifyId": "notify-uuid",
    "isActive": false
  }'

Remove

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalNotifyId": "notify-uuid"
  }'

Managing Alerts

Base URL: https://api.embermind.ch/api/v1/client/alerts

Get Alerts List

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "page": 1,
    "perPage": 20
  }'

Get One Alert

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertId": "alert-uuid"
  }'

Get Alerts Count

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/get-count' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Get Aggregate List

Get aggregated alerts by entity type.

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/get-aggregate-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Mark Alerts as Read

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/toggle-read' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertIdList": ["alert-uuid-1", "alert-uuid-2"],
    "isRead": true
  }'

To mark all alerts as read:

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/toggle-read' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "readAll": true,
    "isRead": true
  }'

Mark Alerts as Done (Resolved)

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/toggle-done' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertIdList": ["alert-uuid-1", "alert-uuid-2"],
    "isDone": true
  }'

Mark Alerts for Deletion

Schedule alerts for automatic deletion.

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/toggle-need-delete' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertIdList": ["alert-uuid-1", "alert-uuid-2"],
    "isNeedDelete": true
  }'

Remove Alerts

Permanently delete alerts.

curl -X POST 'https://api.embermind.ch/api/v1/client/alerts/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertIdList": ["alert-uuid-1", "alert-uuid-2"]
  }'

Examples

Example 1: Create Alert Validator with Email Notification

Scenario: Alert when transaction count exceeds 100 per gate in 10 minutes, send email notification.

Step 1: Create an email notification channel:

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Fraud team email",
    "type": "EMAIL",
    "optSmtpHost": "smtp.company.com",
    "optSmtpPort": "587",
    "optSmtpEmail": "[email protected]",
    "optSmtpPassword": "smtp-password",
    "optSmtpIsSecure": true,
    "optSmtpTargetEmailList": ["[email protected]"]
  }'

Response:

{
  "message": "ok"
}

Step 2: Get the external notify ID:

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Response (excerpt):

{
  "dataList": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "title": "Fraud team email",
      "type": "EMAIL",
      "isActive": true
    }
  ]
}

Step 3: Create the alert validator linked to this notification:

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "High transaction volume per gate",
    "type": "TRANSACTION_COUNT",
    "groupOrderOne": "GATE",
    "retentionPeriodSec": 2592000,
    "externalNotifyIdList": ["11111111-2222-3333-4444-555555555555"],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "binValueList": [],
    "countryCodeList": [],
    "configList": [
      {
        "level": "WARN",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 100,
        "optOperatorOne": "GTE"
      },
      {
        "level": "CRITICAL",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 500,
        "optOperatorOne": "GTE"
      }
    ]
  }'

Now you'll receive:

WARN email when any gate has ≥100 transactions in 10 minutes
CRITICAL email when any gate has ≥500 transactions in 10 minutes

Example 2: Create Conversion Rate Alert for Specific Merchant

Scenario: Alert when conversion rate drops below 80% for a specific merchant (with at least 200 transactions).

Step 1: Get your merchant ID:

curl -X POST 'https://api.embermind.ch/api/v1/client/merchants/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Step 2: Create Telegram notification:

curl -X POST 'https://api.embermind.ch/api/v1/client/external-notifies/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Telegram alerts",
    "type": "TG",
    "optTgBotUsername": "MyCompanyAlertBot",
    "optTgBotToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "optTgBotChatIdList": ["-1001234567890"]
  }'

Step 3: Create the alert validator:

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Low conversion rate for Premium Merchant",
    "type": "TRANSACTION_CONVERSION",
    "groupOrderOne": "MERCHANT",
    "externalNotifyIdList": ["telegram-notify-uuid"],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": ["merchant-uuid"],
    "binValueList": [],
    "countryCodeList": [],
    "configList": [
      {
        "level": "CRITICAL",
        "workerIntervalSec": 300,
        "dataPeriodSec": 3600,
        "optPercent": 80,
        "optOperatorOne": "LT",
        "optMinCount": 200
      }
    ]
  }'

This creates a CRITICAL alert when:

Conversion rate is less than 80%
At least 200 transactions in the last hour
Checked every 5 minutes

Example 3: Update Existing Alert Validator

Step 1: Get current validator settings:

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "searchValue": "High transaction"
  }'

Step 2: Update the validator:

curl -X POST 'https://api.embermind.ch/api/v1/client/alert-validators/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "alertValidatorId": "validator-uuid",
    "title": "Updated: High transaction volume",
    "configList": [
      {
        "level": "INFO",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 50,
        "optOperatorOne": "GTE"
      },
      {
        "level": "WARN",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 150,
        "optOperatorOne": "GTE"
      },
      {
        "level": "CRITICAL",
        "workerIntervalSec": 60,
        "dataPeriodSec": 600,
        "optCount": 300,
        "optOperatorOne": "GTE"
      }
    ],
    "externalNotifyIdList": ["notify-uuid"],
    "cascadeIdList": [],
    "gateIdList": [],
    "merchantIdList": [],
    "binValueList": [],
    "countryCodeList": []
  }'

Data Migration Tip

Important: Alerts are not required during historical data migration. It's recommended to disable them to avoid false positives from historical data.

Contact your manager to disable alerts temporarily.

Next Steps

Data Migration — Import historical transactions
Fingerprint SDK — Collect browser fingerprints