Skip to main content
ShieldLabs sends signed HTTP POST requests to your configured endpoint. Start with Webhook setup to register a receiver.

​
Event types

​
Envelope

​
string
Logical event ID, stable across retries and endpoints. Use it for deduplication.
​
integer
Numeric site scope. Required for multi-account group events.
​
string
required
identification.scored, hre.multi_account.changed or webhook.ping.
​
string
required
Version of the event payload, not the installed SDK package.
​
string
required
Envelope creation time in RFC 3339 UTC.
​
object
Event-specific body. Absent on a connectivity ping.
X-Shield-Event-Id mirrors the event ID. Trust the ID in the verified body, rather than the convenience header by itself.

​
Verification

Use the complete endpoint secret, including whsec_, and the exact bytes received. Compare in constant time. Re-serializing JSON before verification changes the signed bytes. Reject an invalid signature before processing. Keep signing secrets on your backend. Webhook setup has a receiver example.

​
Delivery guarantees

  • At-least-once attempts within a bounded retry policy. Delivery can duplicate or reorder events. There is no exactly-once guarantee.
  • Retry on failure: retries are bounded; keep a way to inspect or recover missed identifications through History.
  • Fast response: persist the event before returning 2xx, then process business actions asynchronously.
  • Deduplicate by event_id. Store it with the accepted identification or group event.
  • History fallback: read an identification by Identification ID if needed, using bounded retries. History is not a replay API for group transitions.
Do not acknowledge a business event before durable receipt. A permanently failing endpoint may never receive an event successfully.

​
Delivery timing

Delivery time varies. Use Identification flow to handle pending results.

​
Service events

Verify sends webhook.ping. Return a successful response after signature verification; do not create an identification from it. Test sends synthetic data. Test Identification IDs may repeat while logical event IDs differ. Never deduplicate all tests by their Identification ID alone. During secret rotation, allow for deliveries signed with either the current or previous secret until the transition is complete.

​
Contract versions

Use event_type and the received schema_version to select your parser. See Versions and availability.

​
Scored data

See identification.scored for fields and an example.

​
High-Risk Events

See per-identification High-Risk Event results for status, confidence and cluster fields.

​
Background multi-account events

See hre.multi_account.changed for enablement, group members, transitions and revisions.