Webhooks

Identification scored

Sent when an identification is complete. The Risk Score describes this identification. Verify HMAC-SHA256 over the exact raw body using the endpoint secret. Deduplicate by the signed event_id. Acknowledge durable acceptance with 2xx within the delivery timeout. Retries preserve the body and ID. Use History for the latest stored result. See https://docs.shieldlabs.ai/setup/webhooks for delivery and signature handling.

postWebhookidentification.scored

Headers

X-Shield-Signaturestring required

sha256= followed by the lowercase hex HMAC-SHA256 of the raw request body:

key: your endpoint's signing secret as UTF-8 bytes, the whsec_ prefix included (not hex- or base64-decoded, not stripped);
message: the exact bytes of the body as received.

Compare it with your own digest in constant time, before parsing the JSON. The example values are the signatures of the example bodies (in their compact form as sent) with the test secret whsec_00112233445566778899aabbccddeeff.

X-Shield-Event-Idstring

Convenience mirror of the signed body event_id. Trust the body after signature verification. Retries preserve the logical event ID.

Payload

event_type'identification.scored' required

Event type. Ignore events whose type you do not know instead of failing.

schema_version'2026-10-13' required

Schema version of this identification event.

created_atstring date-time required

RFC 3339 timestamp in UTC with up to 9 fractional digits (trailing zeros trimmed), for example 2026-09-30T12:34:57.482913041Z. Parse it with a parser that accepts nanoseconds.

event_idstring required

Stable logical event ID. Delivery retries preserve this ID and the signed body.

site_idinteger

Site scope, when available.

Example payload

{
  "created_at": "2026-09-30T12:34:57.482913041Z",
  "data": {
    "identification_id": "a5b7c9d1-e3f5-4a7b-9c1d-3e5f7a9b1c3d",
    "visitor_id": "e9f1a3b5-c7d9-4e1f-8a3b-5c7d9e1f3a5b",
    "device_id": "d8e0f2a4-b6c8-4d0e-bf2a-4b6c8d0e2f4a",
    "session_id": "b6c8d0e2-f4a6-4b8c-8d0e-2f4a6b8c0d2e",
    "cookie_id": "c7d9e1f3-a5b7-4c9d-ae1f-3a5b7c9d1e3f",
    "user_hid": "9f86d081884c7d659a2feaa0c55ad015",
    "domain": "example.com",
    "public_ip": {
      "ip": "203.0.113.24",
      "country": "Netherlands"
    },
    "local_ip": {
      "ip": "203.0.113.24",
      "country": "Netherlands"
    },
    "connection_type": "direct",
    "os": "Windows",
    "browser": "Chrome",
    "device_type": "desktop",
    "traffic_source": {
      "channel": "Google Ads",
      "referrer_domain": "google.com",
      "landing_url": "https://shop.example.com/signup?utm_source=google&utm_medium=cpc&gclid=abc123",
      "click_id_type": "gclid",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "spring_launch"
    },
    "signals": [
      {
        "name": "proxy"
      }
    ],
    "observed_at": "2026-09-30T12:34:57.482913041Z",
    "hre": {
      "account_sharing": {
        "status": "evaluated",
        "level": "medium"
      },
      "account_takeover": {
        "status": "evaluated",
        "level": "medium"
      },
      "impossible_travel": {
        "status": "evaluated",
        "level": "medium"
      }
    }
  }
}

Response

Delivery accepted. The response body is ignored.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.