Skip to main content
Version: 2.0

Alert Webhooks

This page defines the schema of the additional webhook Fraudio sends for an alert. On the Automations page in the Fraudio portal, you select a rule or an alert tag. The webhook triggers for alerts that match that selection.

Configuration​

On the Automations page, select a rule or an alert tag. When an alert matches that rule or tag, Fraudio sends an HTTP POST with the JSON payload below to your endpoint.

Webhook payload​

The payload is JSON.

Schema​

The webhook payload follows this JSON schema:

FieldData TypeDescription
idString (UUID)Unique identifier for the alert notification
tenant_slugStringIdentifier for the client tenant
tenant_api_modeStringAPI mode environment (e.g., "production", "sandbox")
report_group_idString (UUID)Unique identifier for the report group this alert belongs to
scopeStringType of alert. Possible values: "mif", "pfd", "aml"
reported_atDoubleUnix timestamp (in seconds) indicating when the alert was generated
reason_categoryStringCategory code and description of the alert reason
reason_titleStringShort, human-readable title describing why the alert was triggered
scoreDouble | nullRisk score (0.0 - 1.0), where higher values indicate greater risk
tagsArray of StringsArray of relevant tags or categories associated with the alert
classificationObject
Risk assessment information
FieldData TypeDescription
recommendationString | nullRecommended action level. Possible values: "yellow", "red", "black"
priorityString | nullPriority level (lower numbers typically indicate higher priority)
amountDouble | nullTotal monetary amount associated with the alert
currencyString | nullISO 4217 currency code (numeric format, e.g., "978" for EUR)
subjectsArray of Objects
Array of entities involved in the alert

Each subject object contains:

FieldData TypeDescription
typeStringType of entity (e.g., "merchant", "cardholder", "card_token")
idStringClient-specific identifier for the subject entity
nameStringDisplay name of the subject entity (may be "none" if not available)
ruleObject | null
Information about the rule that triggered the alert. Present only if a rule triggered the alert
FieldData TypeDescription
idString (UUID)Unique identifier for the triggered rule
versionIntegerVersion number of the rule
is_shadowBooleanWhether this is a shadow mode alert (not affecting production decisions)
transactionsArray of StringsArray of transaction IDs related to this alert
sourceStringSource 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_business",
"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.