Webhook entità: eventi utente e azienda

Ogni modifica allo stato o ai dati del profilo di un’entità User o Business genera un webhook, così il tuo sistema può reagire in tempo reale. Usa i webhook delle entità per sincronizzare i dati del profilo, propagare i blocchi ad altri sistemi o avviare flussi di compliance a valle.

Catalogo degli eventi

Evento	Trigger
`user.status.updated`	Lo stato di un’entità User cambia (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`)
`user.data.updated`	I campi del profilo di un’entità User cambiano (nome, data di nascita, ritratto, contatori aggregati, metadati)
`business.status.updated`	Lo stato di un’entità Business cambia
`business.data.updated`	I campi del profilo di un’entità Business cambiano (ragione sociale, numero di registrazione, paese, contatori)

activity.created è accettato in subscribed_events e incluso nel tester Try Webhook, ma Didit al momento non lo invia per il traffico di produzione. Non costruire su di esso la sincronizzazione della cronologia.

Didit emette anche eventi di sessione, di transazione e di sessione business che fanno riferimento ai campi delle entità. Vedi:

Webhook KYB — eventi delle sessioni business
Webhook di Transaction Monitoring — eventi delle transazioni
Riferimento webhook — verifica della firma, nuovi tentativi, destinazioni

Struttura del payload

I webhook delle entità sono piatti: non esiste un wrapper data né una chiave event. Leggi webhook_type per instradare l’evento.

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "user.status.updated",
  "timestamp": 1776333600,
  "created_at": 1776333594,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}

Campo	Descrizione
`vendor_user_id` / `vendor_business_id`	Identificativo di Didit per l’entità. Gli eventi `business.*` usano `vendor_business_id`.
`vendor_data`	Il tuo identificativo per l’entità.
`status`	`ACTIVE`, `FLAGGED` o `BLOCKED`.
`previous_status`	Presente solo in `*.status.updated`.
`changed_fields` e `changes`	Presenti solo in `*.data.updated`.
`created_at`	Secondi Unix dell’ultimo aggiornamento dell’entità.
`timestamp`	Secondi Unix in cui Didit ha inviato il webhook.

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

Viene inviato a ogni cambio di stato. Il payload contiene status e previous_status. Non indica il motivo del cambio di stato: se ti serve la causa, apri l’entità nella console.

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

Viene inviato quando cambiano i campi del profilo. changed_fields elenca i campi modificati e changes contiene il valore previous e il valore current di ciascuno.

{
  "event_id": "5d1e8f9a-0c32-4b6a-a7b6-2b9d6f0a3c41",
  "webhook_type": "user.data.updated",
  "timestamp": 1776333700,
  "created_at": 1776333694,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "ACTIVE",
  "changed_fields": ["full_name", "session_count"],
  "changes": {
    "full_name": { "previous": null, "current": "John Doe" },
    "session_count": { "previous": 2, "current": 3 }
  }
}

I campi che possono comparire in changed_fields sono:

User: vendor_data, display_name, full_name, date_of_birth, metadata, portrait_image, issuing_states, approved_emails, approved_phones, features, session_count, approved_count, declined_count, in_review_count, first_session_at, last_session_at.
Business: vendor_data, display_name, metadata, legal_name, registration_number, country_code, session_count, approved_count, declined_count, in_review_count, features, first_session_at, last_session_at.

Usa changed_fields e changes per sincronizzare solo i campi che sono cambiati.

Consegna, nuovi tentativi e firma

Tutti i webhook delle entità seguono il contratto di consegna standard:

Firmati con HMAC-SHA256 nell’header X-Signature-V2 (consigliato), usando il secret_shared_key della destinazione. Vengono inviati anche X-Signature e il deprecato X-Signature-Simple, insieme a X-Timestamp.
Sottoposti a nuovi tentativi fino a 2 volte, dopo circa 1 minuto e circa 4 minuti, quando il tuo endpoint risponde con 5xx o 404, va in timeout o non riesce a connettersi. Il riferimento webhook riporta la politica completa.
Idempotenti: ogni webhook ha un event_id univoco nel payload; deduplica lato tuo.

Vedi Riferimento webhook per la configurazione delle destinazioni ed esempi di codice per la verifica della firma.

Iscrizione

Iscriviti agli eventi delle entità su una destinazione webhook tramite la Management API o la 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"
    ]
  }'

Prossimi passi

Riferimento webhook

Destinazioni, firme, nuovi tentativi e verifica.

Crea destinazione

Registra un nuovo endpoint webhook.

Operazioni utente

Modifiche che attivano i webhook utente.

Panoramica

Prezzi

Workflow e verifica

Revisione e operazioni

Entità (utenti e aziende)

Impostazioni e personalizzazione

Sicurezza e compliance

Didit Academy

Risorse

Webhook entità: eventi utente e azienda

Catalogo degli eventi

Struttura del payload

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

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

Consegna, nuovi tentativi e firma

Iscrizione

Prossimi passi

Riferimento webhook

Crea destinazione

Operazioni utente

​Catalogo degli eventi

​Struttura del payload

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

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

​Consegna, nuovi tentativi e firma

​Iscrizione

​Prossimi passi

Riferimento webhook

Crea destinazione

Operazioni utente

Catalogo degli eventi

Struttura del payload

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

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

Consegna, nuovi tentativi e firma

Iscrizione

Prossimi passi