Webhooks
This page provides an overview of server-to-server network communication known as 'webhooks.'
What is a webhook?
A webhook is when Fingerprint makes an HTTP POST request to your application’s API when an event occurs. This way, Fingerprint 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.
Note:
When multiple webhooks are enabled, events are delivered to each of them simultaneously.
Protecting your webhook
There are two ways of protecting your webhook: basic HTTP authentication and unique urls.
1 - 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.
2 - Unique URL
A url can be unique and no one except you should know it. This doesn't secure the url itself but it won't be searchable or brute forced on the internet. 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 Fingerprint account as follows:
1 - Log in to your Fingerprint account.
2 - Click on the subscription you want to register the webhook for.
3 - Navigate to App Settings -> Webhooks.
Screenshot of how to add a webhook in the Fingerprint dashboard
4 - Click New Webhook. A New Webhook window will be displayed.
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",
// tells whether a visitor was found in a visits history
// nullable: true
"visitorFound": true,
// 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: true
"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: true
"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",
},
// nullable: true
"confidence": {
"score": 0.97
},
// nullable: false
"firstSeenAt": {
// nullable: true
"global": "2022-03-16T11:26:45.362Z",
// nullable: true
"subscription": "2022-03-16T11:31:01.101Z"
},
// nullable: false
"lastSeenAt": {
// nullable: true
"global": "2022-03-16T11:28:34.023Z",
// nullable: true
"subscription": null
}
}
See more information on firstSeenAt/lastSeenAt timestamps here.
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. The retry will take place 5 minutes after the non-2XX response is received or 5 minutes after the timeout takes place.
The retry request will have the same requestID as the first request, so it's possible to use it as an idempotency key.
If you have multiple webhooks configured under one subscription, each request will be treated independently. This means if a timeout or non-2XX response takes place, a retry will only be triggered for the endpoint that caused the issue.
Timeout and errors
Fingerprint expects that integrations respond within 3 seconds of receiving the webhook payload with 2XX status code.
Otherwise, the webhook will be shown as failed on the Webhook events page, headers and response should be < 4KB, otherwise they're truncated.
Updated 17 days ago