# Fraud Prevention API Webhooks: Signatures and Ordering

*Author: Yahor Papou, CMO at ShieldLabs. Updated on October 27, 2026.*

A fraud prevention API webhook receiver has three separate jobs: authenticate the body, accept the event durably, and apply its meaning in the correct order. Combining them in one request handler can turn a duplicate delivery or a late update into a repeated action or an incorrect state change.

The public [ShieldLabs webhook reference](https://docs.shieldlabs.ai/api/webhooks) documents signed bodies, logical event IDs, and possible duplicate or out-of-order delivery. Design around those guarantees. Do not infer exactly-once processing from a successful HTTP response or from a valid signature.

In 2026, we tested these helpers locally with synthetic fixtures: signature verification, malformed envelopes, duplicate identity, and UInt64 revision ordering. The fixture checks cover the code below; they do not measure live detection or production delivery.

## Verification answers one question

HMAC verification checks whether the received bytes match a signature produced with the endpoint secret. It does not establish that the event is new, that its schema is supported, or that it is the newest state for an entity. Those are later processing decisions with different keys.

Use the public [Node SDK](https://github.com/ShieldLabs-ai/shieldlabs-node) with the raw request body:

```javascript
import { webhooks } from '@shieldlabs-ai/node';

const accepted = webhooks.verifySignature(
  rawBody,
  signatureHeader,
  endpointSecret,
);
if (!accepted) throw new Error('Invalid webhook signature');
const event = JSON.parse(Buffer.from(rawBody).toString('utf8'));
```

`rawBody`, `signatureHeader`, and `endpointSecret` are values supplied by your HTTP adapter and server configuration. This snippet is the verification boundary, not a complete receiver. Keep JSON middleware from replacing the byte buffer before that call, and handle invalid JSON after a valid signature as a separate validation failure.

## Receipt identity and entity identity differ

For the modern envelope, use the verified body’s `site_id` and `event_id` to deduplicate receipt. Store the event before acknowledging successful delivery. Then let a worker select the parser for its `event_type` and `schema_version`.

| Purpose | Key or field | Why it exists |
|---|---|---|
| Verify bytes | `X-Shield-Signature` | Authenticate the received body |
| Deduplicate receipt | `site_id` + `event_id` | Avoid repeating one logical event |
| Choose a parser | `event_type` + `schema_version` | Apply the right contract |
| Update group state | Site + epoch + cluster | Keep independent group histories separate |
| Order that state | Numeric revision | Reject an older update |

Do not use a request ID as the universal key for all event types. A group transition is not an identification, and the public contract explicitly separates them. Older envelopes without an event ID need a documented fallback or quarantine path; avoid silently treating every missing value as the same duplicate.

## Compare revisions as integers

The [multi-account group contract](https://docs.shieldlabs.ai/api/webhook-multi-account) represents revisions as UInt64 decimal strings. String ordering puts `"10"` before `"9"`, while JavaScript `Number` cannot represent every UInt64 integer exactly. Validate the decimal form and compare using `BigInt`.

```javascript
const MAX_U64 = (1n << 64n) - 1n;
export function revision(value) {
  if (typeof value !== 'string' || !/^(0|[1-9]\d*)$/.test(value)) {
    throw new Error('Invalid decimal revision');
  }
  const n = BigInt(value);
  if (n > MAX_U64) throw new Error('Revision outside UInt64');
  return n;
}
export function isNewer(incoming, stored) {
  const next = revision(incoming);
  return stored === null || next > revision(stored);
}

```

Keep that comparison inside a database transaction or conditional update. Reading revision 8, deciding revision 9 is newer, and writing later can still overwrite revision 10 if another worker wins the race in between. The comparison helper does not make the storage operation atomic.

The documented group-state key includes `(site_id, source.publication_epoch, cluster_id)`. Preserve that scope. A new publication epoch should not be compared as if its revisions continued an older epoch. The event reference also explains that overlapping active groups can exist; resolving one group does not mean every account is now safe.

## Walk through an out-of-order delivery

Suppose the stored group is at revision 8. Revision 10 arrives, then revision 9, then a retry of revision 10. Accept each new logical event into the inbox, but keep the group projection at revision 10. The last two deliveries should not repeat a customer-facing action or roll state back.

That sequence is an illustrative test, not observed customer behavior. We tested the verification and revision helpers locally with synthetic fixtures. Results: all 16 assertions passed, including comparisons above JavaScript's safe-integer range. Add a storage-level test with two workers attempting updates concurrently. Check the final projection and the side-effect record, not only the receiver's response status.

Also separate durable receipt from business completion. A worker can crash after sending a notification but before marking an event processed. Use an outbox or another idempotent side-effect mechanism with a stable operation key. Receipt deduplication alone does not resolve that crash window.

## Where does the fraud prevention API fit?

A fraud prevention API can provide an on-demand read of a supported identification, while the webhook supplies event delivery. In a fraud detection API integration, define whether the request is retrieving a current identification or trying to recover an event transition; those are different contracts.

The [webhook reference](https://docs.shieldlabs.ai/api/webhooks) documents identification recovery through History and explicitly distinguishes it from replaying group transitions. Use that boundary when designing recovery, and keep unsupported events in a reviewable pending state rather than inventing a result.

## Recover deliberately from unfamiliar events

Store a verified but unsupported event for investigation and hold its business action. Missing schema support should not turn into an approval or a silent drop. Record a concise diagnostic without including secrets or unnecessary customer data in logs.

For group delivery, confirm that the feature is enabled for your site and endpoint as described in the public reference. Existing groups are not automatically replayed when an endpoint is enabled. Maintain a recovery procedure that matches the actual event contract rather than assuming an unlimited replay API.

The [multi-accounting guide](https://shieldlabs.ai/blog/multi-accounting-detection) explains why group evidence matters to benefit abuse. The receiver should transport that evidence reliably without inventing additional detection fields or exposing private detection rules.

## Connect reliable delivery to account investigations

[ShieldLabs risk scoring](https://shieldlabs.ai/products/risk-scoring) provides named risk signals and an explainable risk score. Ready detections cover multi-accounting, account sharing, impossible travel, and account takeover through SDKs, API, and webhooks. Enterprise-level functionality without enterprise pricing helps smaller teams evaluate the account workflow as well as the transport.

[Start Free](https://shieldlabs.ai/pricing) and verify a signed test delivery before attaching irreversible business actions.

## Delivery questions

### Why does a valid signature not prevent replay?

The signature authenticates the body. The documented scheme does not add a separate signed delivery timestamp, so an old valid body can still verify. Durable logical-event deduplication prevents repeating its action. Any age-based business policy needs to account for legitimate delay and preserve a recovery path.

### Should revision 9 replace revision 10 if it arrives later?

No. Arrival time is not the group's revision order. Compare the documented numeric revision within the correct site, epoch, and cluster scope, and apply the comparison atomically in storage. Keep the late event in the inbox for audit without rolling the current projection backward.

### Does a resolved group certify that every member is safe?

No. Resolution describes that particular group under the documented evaluation contract. Other overlapping groups or account risks can remain active. Keep group state separate from an account's overall status, and do not erase unrelated detections when processing one resolution event.

## References

[1] [ShieldLabs: multi accounting detection](https://shieldlabs.ai/blog/multi-accounting-detection)
[2] [ShieldLabs: risk scoring](https://shieldlabs.ai/products/risk-scoring)
[3] [docs.shieldlabs.ai: webhooks](https://docs.shieldlabs.ai/api/webhooks)
[4] [github.com: shieldlabs node](https://github.com/ShieldLabs-ai/shieldlabs-node)
[5] [docs.shieldlabs.ai: webhook multi account](https://docs.shieldlabs.ai/api/webhook-multi-account)

Questions or corrections: [contact@shieldlabs.ai](mailto:contact@shieldlabs.ai).

## Summarize this article with

[ChatGPT](https://chatgpt.com/?q=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering) · [Claude](https://claude.ai/new?q=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering) · [Grok](https://grok.com/?q=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering) · [Grok on X](https://x.com/i/grok?text=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering) · [Perplexity](https://www.perplexity.ai/search/new?q=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering) · [Google AI](https://www.google.com/search?udm=50&aep=11&q=Summarize+this+article+about+fraud+prevention+api.+Explain+the+main+recommendations%2C+trade-offs%2C+and+practical+next+steps%3A+https%3A%2F%2Fshieldlabs.hashnode.dev%2Ffraud-prevention-api-webhooks-signatures-and-ordering)

