Guide to Fingerprint Webhooks: Features and Best Practices
Fingerprint identifies browsers and mobile devices and scores each visit with Smart Signals such as bot detection, VPN use and tampering. Most teams call the Server API after a login or checkout to fetch that result. A webhook reverses the direction: every identification event is posted to your server as it happens, which suits fraud pipelines, analytics stores and anything that needs the full history rather than one lookup.
Below you'll find how a Fingerprint webhook is registered, what an identification event contains, how to check FPJS-Event-Signature, and how the 3-second deadline and single retry shape your receiver.
What are Fingerprint webhooks?
A Fingerprint webhook belongs to an application in your workspace. Once it is enabled, Fingerprint posts each identification event to the URL you gave it, using the same JSON shape as the Server API v4 /events response. You can reuse the parsing code and the type definitions from Fingerprint's Server SDKs.
There is only one kind of delivery, so there is nothing like an event name to route on. What varies is the content: Smart Signals appear only if your pricing tier includes them and the originating device supports them.
Fingerprint webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | fpjs-event-signature |
| Body | JSON |
Other details from the Fingerprint documentation:
- Endpoint URLs must be HTTPS hostnames. IP addresses and plain HTTP are refused.
- A webhook can be limited to one environment, in which case it only reports events from that environment.
- The header holds a comma-separated list of
<version>=<hash>pairs.v1is the only version described. - Fingerprint waits 3 seconds for a
2xx. Headers and response bodies over 4KB are truncated. - A timeout or non-
2xxis retried once, 5 minutes later. - No source IP addresses are published.
Events and payloads
Every delivery is an identification event. Fingerprint's minimal example shows event_id and identification.visitor_, and the reference adds request context and Smart Signals. This abridged example uses fields from Fingerprint's webhook reference:
{
"event_id": "1708102555327.NLOjmg",
"timestamp": 1708102555327,
"linked_id": "somelinkedId",
"environment_id": "ae_47abaca3db2c7c43",
"url": "https://www.example.com/login",
"ip_address": "61.127.217.15",
"identification": {
"visitor_id": "3HNey93AkBW6CRbxV6xP"
},
"incognito": true,
"vpn": true,
"suspect_score": 8
}
event_id is the unique identifier of the request, and its first part is the event time in Unix milliseconds. linked_id is whatever you passed from the client, such as an order or account ID, and is the usual way to join an event back to your own records.
A few fields need care. Fields such as suspect_score, vpn and tampering are missing on the basic Pro tier, and signals that a device type doesn't support are left out, so treat every Smart Signal as optional. With incremental identification, incremental_ means Smart Signals were not computed and their values should be ignored. Webhooks created with Use legacy payload send the deprecated v3 format with camelCase fields such as environmentId.
Setting up Fingerprint webhooks
- In the Fingerprint dashboard, go to Webhooks and click Add webhook.
- Enter the HTTPS URL of your endpoint, for example
https://example.com/webhooks/fingerprint. - Optionally choose an environment to limit the webhook to that environment's events.
- Leave Use legacy payload unchecked unless an existing v3 handler still depends on it.
- Click Create Webhook. The success modal shows the signing key once. Copy it into your server's configuration, for example as
FINGERPRINT_WEBHOOK_KEY. - With your handler deployed, click Send test event.
New webhooks are enabled by default. Use the Edit icon to deactivate one.
On Hookdeck, add a source of the Fingerprint type, give it the signing key as its verification secret, and register the source URL as the webhook URL. To receive events on a local port:
npx hookdeck-cli listen 3000 fingerprint --path /webhooks/fingerprint
Securing Fingerprint webhooks
Split the FPJS-Event-Signature value on commas and keep each v1= entry. Compute a hex HMAC-SHA256 of the raw body with the signing key and accept the request if any v1 value matches in constant time. Ignore versions you don't recognise. The signature documentation gives a test vector: key secret and body payload produce v1=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['fpjs-event-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = signature.split(',').map((part) => part.trim())
.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
With 3 seconds to answer, the handler does as little as possible: verify, record the event against its event_id, and reply.
const express = require('express');
const app = express();
app.post('/webhooks/fingerprint', express.raw({ type: '*/*' }), async (req, res) => {
const signingKey = process.env.FINGERPRINT_WEBHOOK_KEY;
if (!signingKey) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, signingKey)) return res.sendStatus(401);
let event;
try {
event = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
try {
await saveIdentification(event.event_id, {
visitorId: event.identification?.visitor_id,
linkedId: event.linked_id ?? null,
environmentId: event.environment_id ?? null,
raw: event,
});
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
saveIdentification stands for an upsert keyed on event_id, so the retry Fingerprint sends 5 minutes later overwrites the same row. Score the event, or compare it with a login attempt, in a worker that reads from that store.
Legacy v3 webhooks may be protected with Basic HTTP authentication instead of a signature. Hookdeck's Fingerprint source checks only the v1 HMAC, so migrate to the v4 payload before putting Hookdeck in front.
No timestamp is signed, so an old request with a valid signature still verifies. Hookdeck's Fingerprint source applies the same v1 check with no time limit. It answers Fingerprint with 200 immediately and records a signature mismatch as failed verification rather than rejecting the request.
Make Fingerprint webhooks production-ready. Hookdeck Event Gateway answers inside Fingerprint's 3-second window, stores every identification event and keeps retrying your fraud or analytics service well after Fingerprint's one retry is spent.
Fingerprint webhook limitations and pain points
A 3-second deadline
The Problem: A handler that queries a database or calls another service before replying is marked as failed.
Why It Happens: Fingerprint expects a 2xx within 3 seconds and shows anything slower as Failed on the Webhook events page.
Workarounds:
- Persist the raw body and respond before doing any scoring or enrichment.
- Keep cold starts out of the request path, for example with a minimum instance count on serverless hosts.
How Hookdeck Can Help: Hookdeck acknowledges Fingerprint as soon as the request arrives, and your service gets a delivery timeout you configure instead of 3 seconds.
One retry, then nothing
The Problem: An outage longer than about 5 minutes loses identification events.
Why It Happens: Fingerprint retries a failed request once, 5 minutes after the first attempt, and stops.
Workarounds:
- Watch the Webhook events page for failed deliveries.
- For events you can't afford to miss, fetch the result from the Server API by
event_idonce your service recovers.
How Hookdeck Can Help: Hookdeck stores each event and retries delivery to your service on the schedule you set, for as long as your outage lasts, with manual replay for anything that still fails.
Smart Signals vary between events
The Problem: A field your fraud rule depends on is sometimes missing.
Why It Happens: Smart Signals depend on your pricing tier, the platform that produced the event (browser, iOS or Android) and, with incremental identification, whether the request was complete.
Workarounds:
- Read every Smart Signal as optional and decide in advance what a missing value means for your rule.
- Ignore Smart Signals when
incremental_isidentification_ status partially_completed.
How Hookdeck Can Help: Hookdeck filters can hold back events that lack a field such as suspect_score, so your scoring service only receives events it can act on.
The signing key is shown once
The Problem: Losing the key means you can't verify deliveries to that webhook.
Why It Happens: Fingerprint displays the key only in the success modal when the webhook is created.
Workarounds:
- Download or copy the key before closing the modal.
- To replace a key, create a second webhook, deploy its key, then deactivate the old webhook. Both deliver independently in the meantime, so deduplicate on
event_id.
How Hookdeck Can Help: When Fingerprint points at a Hookdeck source, a new key is configured on that source alone, and your services behind it don't change.
Best practices
Keep the raw body
The signature covers the exact bytes Fingerprint sent. Use express.raw or your framework's equivalent, and only call JSON.parse after verification.
Store first, score later
Fraud checks and enrichment don't belong inside the 3-second window. Write the event and respond, then run the work from a queue, as explained in the case for asynchronous webhook processing.
Deduplicate on event_id
The retry repeats the first request's ID, and a webhook replacement can deliver the same event twice. Our webhook idempotency guide covers storing that key alongside the write it caused.
Use linked_id to join your data
Pass an order, session or account ID as linked_id from the client so each webhook can be matched to the action it belongs to without a second API call.
Conclusion
Fingerprint webhooks give you every identification event in the Server API v4 format, signed with a v1 HMAC of the body. The constraints are on timing: 3 seconds to answer, one retry 5 minutes later, and no signed timestamp. A receiver that verifies, stores on event_id and hands the scoring to a worker fits within them.
Hookdeck Event Gateway takes the time pressure off by accepting each Fingerprint event straight away and retrying your service for as long as it needs.
Get started with Hookdeck for free and handle Fingerprint webhooks reliably in minutes.