Skip to main content

​
The snippet does not load

Inspect the browser Network and Console panels. Check the Public Key and import URL, then allow the hosts in CSP setup. Test whether a content blocker is preventing the module or its requests. Use HTTPS; local secure-context exceptions do not remove domain registration requirements.

​
The snippet loads but no check runs

Importing the module alone does not identify a visitor. Call a snippet method. A regular call can be suppressed by the same-user cooldown or an identification already in progress. During a deliberate test, use a force-check method once and inspect its initialization callback. initialized means the check started, not that scoring or delivery completed. Record the Identification ID and inspect the subsequent network response.

​
No webhook arrives

  1. Confirm that the endpoint belongs to the correct domain and is enabled.
  2. Send a connectivity test from Integration > Webhooks.
  3. Inspect endpoint logs for signature failures, timeout or non-2xx responses.
  4. Verify the signature, durably save the event and acknowledge promptly; do slow work afterward.
Delivery has bounded retries, so duplicates and eventual failure are both possible. Retrieve an identification by Identification ID through History when needed. A multi-account group event needs its own enablement and cannot be recovered from identification History.

​
Signature verification fails

Use the endpoint’s whsec_… secret, not a domain API credential. Calculate HMAC-SHA256 over the raw bytes before JSON parsing and compare with X-Shield-Signature in constant time. Parsing and serializing the body changes the bytes. See the receiver example.

​
History returns 400 or an empty result

A 400 means the query is not valid: check the domain UUID, resource name, record id, and list parameters. Send from and to together or omit both. offset, a nested filter, and chips are rejected. A list of visitor, device, or IP returns 403. A missing record returns 404. An empty data list can mean the identification is not stored yet. See History.

​
The Device ID is missing or all zeros

Treat it as unavailable identity evidence. Inspect the score and flags, including the separate Banned IP value of 999, and keep the protected action pending or send it for review. Do not use an all-zero Device ID as a shared identity for unrelated users.

​
A legitimate user scores high

Inspect the named signals and account history. VPN or Private Relay contributes 30, so a legitimate customer can be Suspicious. Verification and review should match the sensitivity of the action. Acting on results gives example responses.

​
No users or High-Risk Events appear

Pass a stable pseudonymous User HID on authenticated calls. Then check event status, evidence coverage and freshness. A group needs qualifying linked activity; a missing evaluation does not mean an evaluated negative result. See High-Risk Events.

​
The identity risk differs from its latest score

These are separate calculations. The latest score describes one check; current identity risk summarizes the associated identification history. High-Risk Events are shown separately. Period changes affect displayed activity. Check Current risk as of and any incomplete-coverage notice on the entity card.

​
HTTP 402, 429 or a score of 999

  • 402: included identification volume is exhausted. Review Billing.
  • 429: a rate limit was reached. Back off and review Rate limits.
  • 999: Banned IP, outside the 0–100 score scale. Handle it before score-based decisions.
See Errors for API-specific responses. For unresolved failures, send Support the domain, Identification ID, timestamp and status, without keys or signing secrets.