Webhook

WEBHOOK event

Example Request Body

{
  "event_id": "<string>",
  "timestamp": 123,
  "linked_id": "<string>",
  "environment_id": "<string>",
  "suspect": true,
  "sdk": {
    "platform": "js",
    "version": "<string>",
    "integrations": [
      {
        "name": "<string>",
        "version": "<string>",
        "subintegration": {
          "name": "<string>",
          "version": "<string>"
        }
      }
    ]
  },
  "replayed": true,
  "identification": {
    "visitor_id": "<string>",
    "visitor_found": true,
    "confidence": {
      "score": 0.5,
      "version": "<string>",
      "comment": "<string>"
    },
    "first_seen_at": 123,
    "last_seen_at": 123
  },
  "supplementary_id_high_recall": {
    "visitor_id": "<string>",
    "visitor_found": true,
    "confidence": {
      "score": 0.5,
      "version": "<string>",
      "comment": "<string>"
    },
    "first_seen_at": 123,
    "last_seen_at": 123
  },
  "tags": {},
  "url": "<string>",
  "bundle_id": "<string>",
  "package_name": "<string>",
  "ip_address": "<string>",
  "user_agent": "<string>",
  "client_referrer": "<string>",
  "browser_details": {
    "browser_name": "<string>",
    "browser_major_version": "<string>",
    "browser_full_version": "<string>",
    "os": "<string>",
    "os_version": "<string>",
    "device": "<string>"
  },
  "proximity": {
    "id": "<string>",
    "precision_radius": 10,
    "confidence": 0.5
  },
  "bot": "not_detected",
  "bot_type": "<string>",
  "cloned_app": true,
  "developer_tools": true,
  "emulator": true,
  "factory_reset_timestamp": 123,
  "frida": true,
  "ip_blocklist": {
    "email_spam": true,
    "attack_source": true,
    "tor_node": true
  },
  "ip_info": {
    "v4": {
      "address": "127.0.0.1",
      "geolocation": {
        "accuracy_radius": 1,
        "latitude": 0,
        "longitude": 0,
        "postal_code": "<string>",
        "timezone": "<string>",
        "city_name": "<string>",
        "country_code": "<string>",
        "country_name": "<string>",
        "continent_code": "<string>",
        "continent_name": "<string>",
        "subdivisions": [
          {
            "iso_code": "<string>",
            "name": "<string>"
          }
        ]
      },
      "asn": "<string>",
      "asn_name": "<string>",
      "asn_network": "<string>",
      "asn_type": "<string>",
      "datacenter_result": true,
      "datacenter_name": "<string>"
    },
    "v6": {
      "address": "2606:4700:3108::ac42:2835",
      "geolocation": {
        "accuracy_radius": 1,
        "latitude": 0,
        "longitude": 0,
        "postal_code": "<string>",
        "timezone": "<string>",
        "city_name": "<string>",
        "country_code": "<string>",
        "country_name": "<string>",
        "continent_code": "<string>",
        "continent_name": "<string>",
        "subdivisions": [
          {
            "iso_code": "<string>",
            "name": "<string>"
          }
        ]
      },
      "asn": "<string>",
      "asn_name": "<string>",
      "asn_network": "<string>",
      "asn_type": "<string>",
      "datacenter_result": true,
      "datacenter_name": "<string>"
    }
  },
  "proxy": true,
  "proxy_confidence": "low",
  "proxy_details": {
    "proxy_type": "residential",
    "last_seen_at": 123
  },
  "incognito": true,
  "jailbroken": true,
  "location_spoofing": true,
  "mitm_attack": true,
  "privacy_settings": true,
  "root_apps": true,
  "suspect_score": 123,
  "tampering": true,
  "tampering_details": {
    "anomaly_score": 0.5,
    "anti_detect_browser": true
  },
  "velocity": {
    "distinct_ip": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "distinct_linked_id": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "distinct_country": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "events": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "ip_events": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "distinct_ip_by_linked_id": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    },
    "distinct_visitor_id_by_linked_id": {
      "5_minutes": 123,
      "1_hour": 123,
      "24_hours": 123
    }
  },
  "virtual_machine": true,
  "vpn": true,
  "vpn_confidence": "low",
  "vpn_origin_timezone": "<string>",
  "vpn_origin_country": "<string>",
  "vpn_methods": {
    "timezone_mismatch": true,
    "public_vpn": true,
    "auxiliary_mobile": true,
    "os_mismatch": true,
    "relay": true
  },
  "high_activity_device": true
}

Authorizations

Authorization · string · header · required

Add your Secret API Key to the Authorization header using the standard Bearer format: Authorization: Bearer <secret_api_key>

Body

application/json

If configured, a Webhook event will be posted to the provided endpoint. The webhook has the same data as our /v4/events endpoint.

Contains results from Fingerprint Identification and all active Smart Signals.

event_id · string · required

Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp For example: 1758130560902.8tRtrH

timestamp · integer<int64> · required

Timestamp of the event with millisecond precision in Unix time.

linked_id · string

A customer-provided id that was sent with the request.

environment_id · string

Environment Id of the event. For example: ae_47abaca3db2c7c43

suspect · boolean

Field is true if you have previously set the suspect flag for this event using the Server API Update event endpoint.

sdk · object

Contains information about the SDK used to perform the request.

Show child attributes

replayed · boolean

true if we determined that this payload was replayed, false otherwise.

identification · object

Show child attributes

supplementary_id_high_recall · object

A supplementary browser identifier that prioritizes coverage over precision. The High Recall ID algorithm matches more generously, i.e., this identifier will remain the same even when there are subtle differences between two requests. This algorithm does not create as many new visitor IDs as the standard algorithms do, but there could be an increase in false-positive identification.

Show child attributes

tags · object

A customer-provided value or an object that was sent with the identification request or updated later.

url · string

Page URL from which the request was sent. For example https://example.com/

bundle_id · string

Bundle Id of the iOS application integrated with the Fingerprint SDK for the event. For example: com.foo.app

package_name · string

Package name of the Android application integrated with the Fingerprint SDK for the event. For example: com.foo.app

ip_address · string

IP address of the requesting browser or bot.

user_agent · string

User Agent of the client, for example: Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....

client_referrer · string

Client Referrer field corresponds to the document.referrer field gathered during an identification request. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, by using a bookmark) For example: https://example.com/blog/my-article

browser_details · object

Show child attributes

proximity · object

Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed.

Show child attributes

bot · enum<string>

Bot detection result:

• not_detected - the visitor is not a bot
• good - good bot detected, such as Google bot, Baidu Spider, AlexaBot and so on
• bad - bad bot detected, such as Selenium, Puppeteer, Playwright, headless browsers, and so on

Available options: not_detected, good, bad

bot_type · string

Additional classification of the bot type if detected.

cloned_app · boolean

Android specific cloned application detection. There are 2 values: * true - Presence of app cloners work detected (e.g. fully cloned application found or launch of it inside of a not main working profile detected). * false - No signs of cloned application detected or the client is not Android.

developer_tools · boolean

true if the browser is Chrome with DevTools open or Firefox with Developer Tools open, false otherwise.

emulator · boolean

Android specific emulator detection. There are 2 values:

• true - Emulated environment detected (e.g. launch inside of AVD).
• false - No signs of emulated environment detected or the client is not Android.

factory_reset_timestamp · integer<int64>

The time of the most recent factory reset that happened on the mobile device is expressed as Unix epoch time. When a factory reset cannot be detected on the mobile device or when the request is initiated from a browser, this field will correspond to the epoch time (i.e 1 Jan 1970 UTC) as a value of 0. See Factory Reset Detection to learn more about this Smart Signal.

frida · boolean

Frida detection for Android and iOS devices. There are 2 values:

• true - Frida detected
• false - No signs of Frida or the client is not a mobile device.

ip_blocklist · object

Show child attributes

ip_info · object

Details about the request IP address. Has separate fields for v4 and v6 IP address versions.

Show child attributes

proxy · boolean

IP address was used by a public proxy provider or belonged to a known recent residential proxy

proxy_confidence · enum<string>

Confidence level of the proxy detection. If a proxy is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high".

Available options: low, medium, high

proxy_details · object

Proxy detection details (present if proxy is true)

Show child attributes

incognito · boolean

true if we detected incognito mode used in the browser, false otherwise.

jailbroken · boolean

iOS specific jailbreak detection. There are 2 values:

• true - Jailbreak detected.
• false - No signs of jailbreak or the client is not iOS.

location_spoofing · boolean

Flag indicating whether the request came from a mobile device with location spoofing enabled.

mitm_attack · boolean

• true - When requests made from your users' mobile devices to Fingerprint servers have been intercepted and potentially modified.
• false - Otherwise or when the request originated from a browser. See MitM Attack Detection to learn more about this Smart Signal.

privacy_settings · boolean

true if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise false.

root_apps · boolean

Android specific root management apps detection. There are 2 values:

• true - Root Management Apps detected (e.g. Magisk).
• false - No Root Management Apps detected or the client isn't Android.

suspect_score · integer

Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights. See more details here: https://dev.fingerprint.com/docs/suspect-score

tampering · boolean

Flag indicating browser tampering was detected. This happens when either:

• There are inconsistencies in the browser configuration that cross internal tampering thresholds (see tampering_details.anomaly_score).
• The browser signature resembles an "anti-detect" browser specifically designed to evade fingerprinting (see tampering_details.anti_detect_browser).

tampering_details · object

Show child attributes

velocity · object

Sums key data points for a specific visitor_id, ip_address and linked_id at three distinct time intervals: 5 minutes, 1 hour, and 24 hours as follows:

• Number of distinct IP addresses associated to the visitor Id.
• Number of distinct linked Ids associated with the visitor Id.
• Number of distinct countries associated with the visitor Id.
• Number of identification events associated with the visitor Id.
• Number of identification events associated with the detected IP address.
• Number of distinct IP addresses associated with the provided linked Id.
• Number of distinct visitor Ids associated with the provided linked Id.

The 24h interval of distinct_ip, distinct_linked_id, distinct_country, distinct_ip_by_linked_id and distinct_visitor_id_by_linked_id will be omitted if the number of events for the visitor Id in the last 24 hours (events.['24h']) is higher than 20.000.

All will not necessarily be returned in a response, some may be omitted if the associated event does not have the required data, such as a linked_id.

Show child attributes

virtual_machine · boolean

true if the request came from a browser running inside a virtual machine (e.g. VMWare), false otherwise.

vpn · boolean

VPN or other anonymizing service has been used when sending the request.

vpn_confidence · enum<string>

A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods.

Available options: low, medium, high

vpn_origin_timezone · string

Local timezone which is used in timezone_mismatch method.

vpn_origin_country · string

Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown).

vpn_methods · object

Show child attributes

high_activity_device · boolean

Flag indicating if the request came from a high-activity visitor.

Response

200

Return a 200 status to indicate that the data was received successfully