Skip to main content
ShieldLabs uses different models for a scored identification, a multi-account group and a History card. Choose by event_type and schema_version; do not assume that every response has an Identification ID or a Risk Score. For definitions of individual fields, start with the product glossary for identifiers and risk signals, or the integration glossary for webhook envelopes, revision, level, kind, client identity and API terms.

WebhookEvent

The signature is in the X-Shield-Signature header, not the JSON body. Verify the raw bytes before trusting any field.

Scored identification

identification.scored contains the identification’s IDs, user, IPs, device information, traffic attribution, score, signal contributions, detection flags and three per-identification High-Risk Event results. The complete field list and example are maintained in one place: Webhook reference.
  • identification_id joins the result to a check; event_id deduplicates delivery.
  • observed_at is the original observation time; created_at is event creation time.
  • risk_score is authoritative. A weight sum is not a substitute.
  • hre holds Account sharing, Account takeover and Impossible travel. Multi-accounting has a separate event.

Detection flags

data.detection_flags in an identification.scored webhook contains these 20 boolean keys. The weight belongs to the corresponding risk signal; the flag itself is true or false. Use the returned risk_score as the final result. These are webhook keys. A History card lists signal names in signals.items and does not repeat detection_flags. See Response contracts. Read signals for the contributions returned with a check.

WebhookSignal

One score contribution in data.signals:
name is the exported signal slug; weight is its reported contribution. Read boolean decisions from detection_flags. See signal names and weights.

High-Risk Events

For the per-identification results, read status before level: A detected result has level: "medium" or "high". An optional cluster reference links it to a published group. Do not invent a cluster ID from a request or device ID. The multi-account group contract instead carries action, cluster_id, members and revisions. It has no identification risk_score.

History card

A list returns { "data": [ ... ], "next_page_token": null }. One record returns { "data": { ... } }. Each item is an entity card. Read risk.score only when risk.state is ok. That score is 0–100. Banned IP (999) is a scored-webhook marker, not a History card score. Webhook data.signals also includes each contribution. Webhook detection_flags is not repeated on the card. Response contracts explains the difference. See Search and Card for pagination, authentication and examples.

Machine-readable schema

Download the OpenAPI bundle for endpoint schemas. For webhooks, select the model by the received event_type and schema_version.