# 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. `v1` is the only version described.
* Fingerprint waits 3 seconds for a `2xx`. Headers and response bodies over 4KB are truncated.
* A timeout or non-`2xx` is 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_id`, and the reference adds request context and Smart Signals. This abridged example uses fields from Fingerprint's [webhook reference](https://docs.fingerprint.com/reference/posteventwebhook):

```json
{
  "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_identification_status: "partially_completed"` 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

1. In the Fingerprint dashboard, go to **Webhooks** and click **Add webhook**.
2. Enter the HTTPS URL of your endpoint, for example `https://example.com/webhooks/fingerprint`.
3. Optionally choose an environment to limit the webhook to that environment's events.
4. Leave **Use legacy payload** unchecked unless an existing v3 handler still depends on it.
5. Click **Create Webhook**. The success modal shows the signing key once. Copy it into your server's configuration, for example as `FINGERPRINT_WEBHOOK_KEY`.
6. 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:

```bash
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](https://docs.fingerprint.com/docs/webhooks#webhook-signatures) gives a test vector: key `secret` and body `payload` produce `v1=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4`.

### Node.js verification

```javascript
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.

```javascript
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](/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_id` once 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_identification_status` is `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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### 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](/webhooks/guides/implement-webhook-idempotency) 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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) for free and handle Fingerprint webhooks reliably in minutes.