Protecting from payload replay attacks

The replayed flag is a security mechanism designed to detect and mitigate replay attacks by verifying the uniqueness of the payload generated by our JavaScript agent. If the same payload is seen more than once, the replayed flag is raised silently, without exposing any information to the attacker.

Purpose

This flag helps protect against abuse scenarios where attackers attempt to reuse a previously captured payload to manipulate the output of their visitor ID or Smart signals. The attacker might be trying to evade your Fingerprint-based site protections or simply cause damage by inflating your API call volume.

📘
Request vs. response replay attacks
The replayed flag is designed to prevent payload replay attacks targeted against the Fingerprint API. To prevent replay attacks against your own server endpoints, where the attacker reuses something from the Fingerprint API response (request_id or visitor_id), see Protecting from client-side tampering.

Prevent Replay Attacks

The replayed flag is specifically designed to detect the reuse of payloads generated by our JavaScript agent. If an attacker captures and attempts to reuse one of these payloads to spoof a legitimate visitor_id, the system sets the replayed flag to true.

The replayed is shown in:

See the snippet below for an example of protecting your identification logic and preventing account takeovers, session spoofing, and other impersonation attacks.

// ...
export async function loginHandler(request) {
  const { sealedResult } = await req.json();
  // see our Sealed Client Results guide for more information
  // https://dev.fingerprint.com/docs/sealed-client-results
  const result = unsealEvent(sealedResult) // result is the event payload

  if (result.products.identification.data.replayed == true) {
     return Response.json(
      { message: "Suspicious identification payload detected." },
      { status: 403 },
    );
  }
  // ...
}

Block Fraudulent IP Addresses

Replay activity frequently originates from bots or attackers operating behind suspicious IP addresses. By monitoring for the replayed flag, you can identify and filter out these potentially malicious sources. A common approach is to set up a webhook that inspects incoming traffic for replayed: true flags.

// ...
export async function webhookHandler(request: Request) {
  const event = await request.json();
  
  if (event.replayed) {
     saveIpForBlocklistExport(event.ip)
  }
  
  fingerprintWebhookDatabase.add(event);
  return Response.json({ message: 'Webhook received', status: 200 });
}

When such a flag is detected, you can save the IP address and temporarily add the associated IP address to our request filtering blocklist through the Dashboard. The blocklist should be cleared after a few days to prevent false positives caused by IP rotations.

Notice Malicious Behavior

Replayed payloads are a strong signal of potentially harmful behavior. While legitimate traffic rarely triggers this flag, attackers using automation or engaging in abusive activity—such as scraping, credential stuffing, or API probing—often might. By tracking and analyzing these replay flags, you can proactively detect and mitigate broader patterns of malicious behavior.

This becomes even more effective when combined with other Smart Signals like datacenter or bot.

SELECT ip, visitorId, jsonExtract("ipInfo", "v4.geolocation.country.code")
FROM my_fingeprint_webhook_backups
WHERE replayed = "true" AND 
(
  jsonExtract("bot", "result") = "bad" OR
  jsonExtract("ipInfo", "v4.geolocation.datacenter.result") = "true"
)

Availability

The replayed flag is available to all customers, as part of our core security feature set.