Skip to main content
Add a webhook to receive identification results on your backend. Each domain supports up to 10 endpoints, each with its own HTTPS URL and signing secret.

Register an endpoint

  1. Open Integration > Webhooks in the analytics dashboard and select the domain.
  2. Choose Add endpoint, enter its name and HTTPS URL, and save.
  3. Store its whsec_… signing secret as a backend environment variable.
  4. Choose Verify for a signed connectivity ping, then Test for a sample identification.
Webhooks are optional: identifications still run and are available through History when no endpoint is registered.

Verify and store the event

The following Node.js example verifies the raw body before parsing it. saveInboxOnce is an application-owned durable database operation, described below.
Node.js / Express
Implement saveInboxOnce with a unique constraint on the logical event ID and a durable inbox row. A duplicate insert must succeed without scheduling a second business action. The worker must apply its business change and mark the inbox record processed in one transaction, or use an equally idempotent external operation. The example uses Express’s default raw-body size limit. Set an explicit limit suitable for your expected payloads, especially complete multi-account member lists.

Route by event type

  • identification.scored: join data.identification_id to the protected action. Read the score, flags and three per-identification account results.
  • hre.multi_account.changed: update the group by cluster ID and revision. It has no Identification ID or identification score.
  • webhook.ping: connectivity check only.
See the full payload reference. Do not assume test payloads have unique Identification IDs; current events are deduplicated by event_id.

Enable multi-account group notifications

The group event must be enabled for your site and opted in on the endpoint with multiaccount: true. It is disabled by default. Confirm availability with support before relying on it. Existing groups are not automatically replayed when you subscribe.

Delivery and recovery

Acknowledge promptly after durable receipt. Process heavier work after acknowledgment. ShieldLabs can retry failed delivery, so handlers must tolerate duplicates and out-of-order events. For a missing scored result, query History by Identification ID with bounded retries. History reads do not recover missed group transitions. Follow the group ordering rules for those events.

Rotate a secret

Each endpoint has a separate secret. During rotation, accept either the current or previous secret for a transition period. Retire the previous secret after you have confirmed that deliveries signed with it have finished.

Next steps