FingerprintJS

Webhooks

This page provides an overview of server-to-server network communication known as 'webhooks.'

What Is a Webhook?

A webhook is when FingerprintJS makes an HTTP POST request to your application’s API when an event occurs. This way, FingerprintJS is able to immediately notify you when an event occurs and your application doesn’t have to perform complicated polling to determine if something new occurred. Webhooks are asynchronous and don't incur performance overhead when enabled.

Protecting Your Webhook

There are two ways of protecting your webhook: IP address whitelisting and basic HTTP authentication.

1 - IP Address Whitelisting

Webhook requests are made from static IP addresses that you can add to your firewall rules.

REGIONIP
US east (N. Virginia)3.217.157.129
EU central (Frankfurt)18.196.47.40

2 - HTTP Basic Authentication

An easy way to protect your API is through basic HTTP authentication. Almost all web servers can be configured to require a username and password to access a URL.

To ensure your data is encrypted, we require using HTTPS for all webhook communication.

Identification Webhook

This webhook is a key part of our webhook system. It occurs every time you make an identification API request.

As soon as we receive the identification request, our servers process the received information and make an HTTP POST request to your webhook URL.

Registering the Identification Webhook

You can register webhooks from your FingerprintJS account as follows:

1 - Log in to your FingerprintJS account.
2 - Click on the subscription you want to register the webhook for.
3 - Click Webhooks in the sidebar navigation.

4 - Click New Webhook. A New Webhook window will be displayed.

5 - Fill in the URL field. Note that a webhook must use an HTTPS domain. It cannot be an IP or a non-HTTPS domain. The rest of the fields in the New Webhook window, i.e. Basic authentication user, Basic authentication password and Description, are optional.

📘

Note:

As in the screenshot above, webhooks are set to Active by default. You can manually deactivate your webhooks by toggling the Active switch off.

6 - Click Save.

Identification Webhook Object Format

{
  // Unique request identifier
  // nullable: false, maxLength: 20
  "requestId": "Px6VxbRC6WBkA39yeNH3",
  // customer-provided data, for example requestType and yourCustomId
  // both the tag and the information it contains are optional
  // and only for the customer's need.
  // nullable: true, maxLength: 4096
  "tag": {
    "requestType": "signup",
    "yourCustomId": 45321
  },
  // user-provided scalar identifier
  // nullable: true, maxLength: 4096
  "linkedId": "any-string",
  // persistent visitor identifier
  // helpful to detect anonymous or private mode users
  // nullable: false, maxLength: 20
  "visitorId": "3HNey93AkBW6CRbxV6xP",
  // timestamp in milliseconds (since unix epoch)
  // nullable: false
  "timestamp": 1554910997788,
  // if the page view was made in incognito or private mode
  // nullable: false
  "incognito": false,
  // URL where the API was called in the browser
  // nullable: false, maxLength: 4096
  "url": "https://banking.example.com/signup",
  // The URL of a client-side referrer
  // nullable: true, maxLength: 4096
  "clientReferrer": "https://google.com?search=banking+services",
  // nullable: false, maxLength: 40
  "ip": "216.3.128.12",
  // nullable: false
  "ipLocation": {
    // miles
    // nullable: true
    "accuracyRadius": 1,
    // nullable: true
    "city": {
      // nullable: true, maxLength: 4096
      "name": "Bolingbrook"
    },
    // nullable: true
    "continent": {
      // nullable: true, maxLength: 2
      "code": "NA",
      // nullable: true, maxLength: 40
      "name": "North America"
    },
    // nullable: true
    "country": {
      // nullable: true, maxLength: 2
      "code": "US",
      // nullable: true, maxLength: 250
      "name": "United States"
    },
    // nullable: true
    "latitude": 41.12933,
    // nullable: true
    "longitude": -88.9954,
    // nullable: true
    "organization": {
      // nullable: true, maxLength: 4096
      "domain": "comcast.net",
      // nullable: true, maxLength: 4096
      "isp": "Comcast Cable",
      // nullable: true, maxLength: 4096
      "legalName": "Comcast Cable Communications, LLC",
      // nullable: true, maxLength: 4096
      "name": "Comcast Cable"
    },
    // nullable: true, maxLength: 40
    "postalCode": "60547",
    // nullable: true
    "subdivisions": [
      {
        // nullable: true, maxLength: 250
        "isoCode": "IL",
        // nullable: true, maxLength: 250
        "name": "Illinois"
      }
    ],
    // nullable: true, maxLength: 250
    "timezone": "America/Chicago"
  },
  // nullable: false
  "browserDetails": {
    // nullable: true, maxLength: 250
    "browserName": "Chrome",
    // nullable: true, maxLength: 250
    "browserFullVersion": "73.0.3683.86",
    // nullable: true, maxLength: 250
    "browserMajorVersion": "73",
    // nullable: true, maxLength: 250
    "os": "Mac OS X",
    // nullable: true, maxLength: 250
    "osVersion": "10.14.3",
    // nullable: true, maxLength: 250
    "device": "Other",
    // nullable: true, maxLength: 4096
    "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86",
  }
}

Testing Your Webhooks With CURL

Once you add the webhook to your system, you can test it as follows:

curl <your-webhook-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "tag": 2718281828, "visitorId": "3HNey93AkBW6CRbxV6xP", /* remaining fields here */}'

Updated 12 days ago

Webhooks


This page provides an overview of server-to-server network communication known as 'webhooks.'

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.