Entity Webhooks

Every change to a User or Business entity emits a webhook so your system can react in real time. Use entity webhooks to sync profile data, propagate blocks to other systems, or trigger downstream compliance flows.

Event catalog

Event	Trigger
`user.status.updated`	A User entity’s status changes (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`)
`user.data.updated`	A User entity’s profile fields change (name, DOB, portrait, aggregate counters, metadata)
`business.status.updated`	A Business entity’s status changes
`business.data.updated`	A Business entity’s profile fields change (legal name, registration number, country, counters)
`activity.created`	A new activity is logged against an entity (manual action, automated check, note)

Didit also emits session, transaction, and business-session events that reference entity fields. See:

KYB webhooks — business session events
Transaction Monitoring webhooks — transaction events
Webhooks reference — signature verification, retries, destinations

Payload shapes

All entity webhooks share a common envelope:

{
  "event": "user.status.updated",
  "application_id": "app_abc123",
  "timestamp": "2026-04-16T10:00:00Z",
  "data": {
    "vendor_data": "user-42",
    "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
    "status": "BLOCKED",
    "previous_status": "ACTIVE",
    "reason": "session_declined",
    "actor": "system",
    "metadata": { ... }
  }
}

`user.status.updated` / `business.status.updated`

Fires on every status change. The reason field tells you why the change happened:

Reason	Description
`manual`	An analyst changed the status from the console
`api`	The status was changed via `PATCH /v3/users/{vendor_data}/update-status/`
`session_declined`	Linked session was declined and auto-block is enabled
`blocklist_match`	Entity matched a blocklist entry (face, document, email, phone)
`transaction_rule`	A transaction rule action moved the entity to FLAGGED or BLOCKED
`ongoing_monitoring`	Periodic AML rescan surfaced a new hit

`user.data.updated` / `business.data.updated`

Fires when profile fields change. The payload includes the full updated entity:

{
  "event": "user.data.updated",
  "application_id": "app_abc123",
  "timestamp": "2026-04-16T10:00:00Z",
  "data": {
    "vendor_data": "user-42",
    "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
    "display_name": "Jane Doe",
    "full_name": "John Doe",
    "date_of_birth": "1990-01-01",
    "status": "ACTIVE",
    "session_count": 3,
    "approved_count": 2,
    "declined_count": 0,
    "in_review_count": 1,
    "features": {
      "id_verification": "APPROVED",
      "liveness": "APPROVED",
      "face_match": "APPROVED",
      "aml": "IN_REVIEW"
    },
    "changed_fields": ["full_name", "session_count", "in_review_count", "features"]
  }
}

Use changed_fields to efficiently sync only the fields that changed.

`activity.created`

Fires whenever an activity record is created about a User or Business entity. Activities form the entity’s timeline — the backend writes one for every material event, across five source categories:

Source	Examples
`CUSTOMER`	End-user actions (profile edits, Key People submissions)
`SYSTEM`	Backend automation (status transitions, ongoing-monitoring rescans, threshold triggers)
`VERIFICATION`	KYC / KYB session lifecycle (session created, feature finished, decision rendered)
`TRANSACTION`	Transaction monitoring events (rule triggers, severity shifts, case openings)
`REVIEW`	Console reviewer actions (notes, tag changes, status overrides)

Example payload:

{
  "event": "activity.created",
  "application_id": "app_abc123",
  "timestamp": "2026-04-18T10:05:00Z",
  "data": {
    "subject_kind": "USER",
    "subject_vendor_data": "user-42",
    "activity_type": "note_added",
    "source": "REVIEW",
    "status": null,
    "title": "Analyst note",
    "description": "Requested additional proof of address",
    "metadata": {},
    "custom_values": {},
    "occurred_at": "2026-04-18T10:05:00Z",
    "session_id": null,
    "business_session_id": null,
    "transaction_id": null
  }
}

Key fields:

subject_kind — USER, BUSINESS, or EXTERNAL (a counterparty not registered as one of your entities).
subject_vendor_data — the entity’s vendor_data when applicable.
source — one of the five categories above.
activity_type — machine-readable type tag (e.g. note_added, status_changed, session_completed, rule_triggered).
title / description — human-readable summary; safe to render in your timeline UI.
session_id, business_session_id, transaction_id — FK identifiers when the activity is tied to a specific session or transaction.

Use activity.created to mirror the Didit timeline into your own audit / compliance log, trigger follow-up workflows on specific activity types, or power a customer-facing timeline view.

Delivery, retries, and signing

All entity webhooks follow the standard delivery contract:

Signed with HMAC-SHA256 via the X-Didit-Signature header (secret shared key on your destination).
Retried with exponential backoff on non-2xx responses (1s → 2s → 4s → … up to 5 retries over ~24 hours).
Idempotent — every webhook has a unique event_id in the payload; de-dupe on your side.

See Webhooks reference for destination setup and signature verification code samples.

Subscribing

Subscribe to entity events on a webhook destination via the Management API or Business Console:

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Entity sync",
    "url": "https://yourapp.com/webhooks/didit",
    "subscribed_events": [
      "user.status.updated",
      "user.data.updated",
      "business.status.updated",
      "business.data.updated",
      "activity.created"
    ]
  }'

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

Event catalog

Payload shapes

`user.status.updated` / `business.status.updated`

`user.data.updated` / `business.data.updated`

`activity.created`

Delivery, retries, and signing

Subscribing

Next steps

Webhooks reference

Create destination

User operations

​Event catalog

​Payload shapes

​user.status.updated / business.status.updated

​user.data.updated / business.data.updated

​activity.created

​Delivery, retries, and signing

​Subscribing

​Next steps

Webhooks reference

Create destination

User operations

Event catalog

Payload shapes

`user.status.updated` / `business.status.updated`

`user.data.updated` / `business.data.updated`

`activity.created`

Delivery, retries, and signing

Subscribing

Next steps