ShieldLabs sends signed HTTP POST requests to your configured endpoint. Start with Webhook setup to register a receiver.
Event types
Envelope
Logical event ID, stable across retries and endpoints. Use it for deduplication.
Numeric site scope. Required for multi-account group events.
identification.scored, hre.multi_account.changed or webhook.ping.
Version of the event payload, not the installed SDK package.
Envelope creation time in RFC 3339 UTC.
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.