minFraud Alerts

After initial scoring, we continue to monitor transactions with risk scores less than or equal to 10 for another 24 hours. If we receive new information related to these transactions that lead to a transaction having a re-calculated risk score greater than or equal to 75, we send out a minFraud Alert.

You can receive minFraud Alerts via email or webhook.

Receive minFraud Alerts via email

You can set an email where you would like to receive minFraud Alerts through the minFraud Alert configuration screen in your account portal (login required).

Receive minFraud Alerts via webhook

You can also receive minFraud Alerts by webhook, and integrate your own response to these alerts on your server. You can configure your minFraud Alert webhook settings through the minFraud Alert configuration screen in your account portal (login required).

Configuration

The alert webhook URL should be an HTTPS endpoint that accepts GET requests. The User-Agent of the minFraud Alert service is MaxMind MinFraud Alert Robot.

Parameters

The following are the parameters that will be included in the query string of the request. Additional parameters may be added in the future.

ParameterDescription
cityThe billing city included in the original minFraud request.
countryThe billing country included in the original minFraud request.
dateThe date of the original minFraud request, e.g., Nov. 1, 2019.
domainThe email domain included in the original minFraud request.
iThe IP address included in the original minFraud request.
maxmindIDThe minFraud Legacy maxmindID of the original minFraud request.
minfraud_idThe minFraud ID of the original minFraud request.
new_risk_scoreThe updated risk score, calculated after your initial query with additional information.
old_risk_scoreThe risk score as originally calculated.
postalThe billing postal included in the original minFraud request.
reasonA human-readable description of why the minFraud alert was sent. See below for the current list of possible reasons.
reason_codeA fixed, machine-readable code for the reason why the minFraud alert was sent. See below for the current list of possible reasons.
regionThe billing region included in the original minFraud request.
shop_idThe shop ID included in the original minFraud request. This will only be set if the original request included a shop ID.
txnIDThe transaction ID included in the original minFraud request.
updated_atThe date and time at which the new risk score was calculated, in RFC3339 format, e.g., 2019-11-01T12:34:56Z

Possible alert reasons

These are the possible reason_codes which might be returned with a minFraud Alert. These codes are subject to change.

reason_codereason
CARDER_EMAILEmail on order was flagged as high-risk email, as it was associated with another high-risk order
HIGH_RISK_DEVICEDevice ID has been marked as a high-risk device ID
HIGH_RISK_IPIP address has been marked as a high-risk IP
HOSTING_PROVIDERIP is from High Risk Hosting Provider
POSTAL_VELOCITYIP address had high velocity of orders (e.g. different zipcodes on same IP address)

Securing your webhook

You can secure your webhook by verifying that alert requests come from MaxMind:

Alert webhook request IPs

minFraud alert requests may come from one of the following IP addresses. This list is subject to change.

  • 35.186.179.139

Signed requests

Alert requests can be signed by MaxMind. To enable signed requests, visit your minFraud Alert configuration screen in your account portal (login required) and set an Alert Webhook Secret.

Once you set a secret, each alert request will have an HTTP header with a signature of the request. You can calculate the signature of the request on your server and check it matches the signature in the header to verify the request is authentic.

For example, if the secret is supersekret-0123456789 and the alert request is:

Then the request will include this header:

The signature is the hex encoded HMAC-SHA256 of the URL query parameters - everything after the ?. In this case, the text to be signed is:

You can check the signaturing using something like the following code:

To avoid timing attacks, please use a secure comparison function rather the equals operator of your language.

This page was last updated on January 25, 2022.