Skip to main content
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

EventTrigger
user.status.updatedA User entity’s status changes (ACTIVE ↔ FLAGGED ↔ BLOCKED)
user.data.updatedA User entity’s profile fields change (name, DOB, portrait, aggregate counters, metadata)
business.status.updatedA Business entity’s status changes
business.data.updatedA Business entity’s profile fields change (legal name, registration number, country, counters)
activity.createdA 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:

​
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:
ReasonDescription
manualAn analyst changed the status from the console
apiThe status was changed via PATCH /v3/users/{vendor_data}/update-status/
session_declinedLinked session was declined and auto-block is enabled
blocklist_matchEntity matched a blocklist entry (face, document, email, phone)
transaction_ruleA transaction rule action moved the entity to FLAGGED or BLOCKED
ongoing_monitoringPeriodic 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": "Jane Margaret Doe",
    "date_of_birth": "1990-01-15",
    "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:
SourceExamples
CUSTOMEREnd-user actions (profile edits, Key People submissions)
SYSTEMBackend automation (status transitions, ongoing-monitoring rescans, threshold triggers)
VERIFICATIONKYC / KYB session lifecycle (session created, feature finished, decision rendered)
TRANSACTIONTransaction monitoring events (rule triggers, severity shifts, case openings)
REVIEWConsole 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"
    ]
  }'

​
Next steps

Webhooks reference

Destinations, signatures, retries, and verification.

Create destination

Register a new webhook endpoint.

User operations

Changes that trigger user webhooks.