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 happened. 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
Global region3.217.157.129
EU region18.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.

Screenshot of how to add a webhook in the FingerprintJS dashboardScreenshot of how to add a webhook in the FingerprintJS dashboard

Screenshot of how to add a webhook in the FingerprintJS dashboard

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

Screenshot of the form required to create a new webhookScreenshot of the form required to create a new webhook

Screenshot of the form required to create a new webhook

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,
  // time in RFC3339 format
  // nullable: false
  "time": "2019-10-12T07:20:50.52Z",
  // 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, 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 */}'

Retries

Every request is retried once if it timed out or returned a non-2XX response. Delay is set to 5 minutes.
The retry request will have the same requestID as the first request, so it's possible to use it as an idempotency key.


Did this page help you?