Webhook KYB: eventi, payload e firma HMAC

Didit’s KYB webhooks comunicano al tuo backend quando una sessione di verifica aziendale cambia stato o quando un revisore o il registro modifica i suoi dati. Le entità aziendali hanno eventi propri. Sottoscrivi gli eventi che ti interessano tramite la API delle destinazioni webhook oppure dalla Business Console.

Catalogo degli eventi

Gli eventi di sessione sono condivisi tra le sessioni User e Business. Il campo session_kind nel payload indica a quale tipo di sessione si riferisce l’evento. Gli eventi a livello di entità sono separati da quelli a livello di sessione.

Eventi a livello di sessione

Evento	Quando viene inviato
`status.updated`	Lo stato di una sessione è cambiato. Per le sessioni Verifica aziendale (KYB) il payload contiene `session_kind: "business"`. Questo è l’evento da seguire per monitorare i progressi.
`data.updated`	Un revisore ha modificato i dati del registro, ha saltato o rigenerato i Key People nella console, oppure il registro ha segnalato una modifica (quando il monitoraggio del registro è disponibile). Il campo `trigger` indica quale dei casi si è verificato.

data.updated non viene inviato quando il richiedente carica un documento o invia i Key People, né quando una nuova scansione AML termina. Per seguire questi progressi usa status.updated oppure recupera la decisione della sessione.

Eventi delle entità aziendali

Evento	Quando viene inviato
`business.status.updated`	Lo stato della entità aziendale collegata è cambiato (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	I campi del profilo dell’entità aziendale o i contatori aggregati sono cambiati.

Puoi sottoscrivere qualsiasi combinazione di eventi sulla tua destinazione webhook. Consulta i webhook delle entità per il riferimento completo degli eventi delle entità aziendali e degli utenti.

Struttura del payload

I webhook di sessione usano un payload piatto, senza un wrapper data. La busta, le intestazioni della firma e tutti i campi condivisi sono documentati nel riferimento dei webhook. Una sessione KYB aggiunge questi campi:

Campo	Tipo	Descrizione
`session_kind`	`"business"`	Consente a un gestore generico di distinguere tra KYC e KYB.
`business_session_id`	`uuid`	Uguale a `session_id`.
`vendor_business_id`	string	Il tuo identificativo per l’entità aziendale, se fornito alla creazione della sessione.
`status`	string	L’etichetta esatta, ad esempio `"In Progress"`, `"Approved"` o `"Awaiting User"`. Vedi stati.
`trigger`	string	Facoltativo. Il motivo per cui il webhook è stato inviato. Su `data.updated` per KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` o `"kyb_registry_change"`.
`decision`	object	Presente quando `status` è `Approved`, `Declined`, `In Review` o `Abandoned`. Ha la stessa struttura di `GET /v3/session/{id}/decision/`, vedi lo schema della risposta.
`resubmit_info`	object	Presente quando `status` è `Resubmitted`.

`status.updated` per una sessione KYB

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

Il blocco decision contiene registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] e gli altri array KYB.

`data.updated` per una sessione KYB

data.updated contiene la stessa busta piatta di status.updated, più un trigger che indica il motivo dell’invio. Quando lo stato della sessione è Approved, Declined, In Review o Abandoned, contiene anche la decision corrente. Richiedi di nuovo la decisione per vedere cosa è cambiato. Il payload non contiene un elenco changed_fields.

`business.status.updated` e `business.data.updated`

Anche gli eventi delle entità sono piatti. Contengono vendor_business_id, vendor_data, status (ACTIVE, FLAGGED o BLOCKED) e created_at. business.status.updated aggiunge previous_status. business.data.updated aggiunge changed_fields e una mappa changes di { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

Verifica della firma

Ogni webhook è firmato con HMAC-SHA256 usando il segreto condiviso della tua destinazione. Verifica il corpo grezzo della richiesta con l’header X-Signature-V2 (consigliato) e rifiuta le consegne il cui X-Timestamp è più vecchio di 300 secondi. Il riferimento dei webhook elenca tutte le intestazioni della firma, la sovrapposizione durante la rotazione del segreto di firma ed esempi di codice.

Politica dei nuovi tentativi

Una risposta 5xx o 404, un timeout o un errore di connessione attiva fino a 2 nuovi tentativi, dopo circa 1 minuto e circa 4 minuti, poi la consegna viene scartata.
Le altre risposte 4xx e 3xx non vengono ritentate.
Ogni nuovo tentativo mantiene lo stesso event_id, quindi deduplica in base a quello.
Puoi reinviare una consegna dal registro delle consegne della destinazione. Il riferimento dei webhook contiene la politica completa.

Sottoscrizione

Sottoscrivi gli eventi che ti interessano su una destinazione webhook:

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

Filtra le sessioni aziendali dal tuo lato verificando session_kind === "business" negli eventi status.updated e data.updated.

Prossimi passi

Riferimento dei webhook

Destinazioni, firma, nuovi tentativi, schemi comuni.

Stati

Riferimento degli stati di sessione e di funzionalità.

Schema della risposta

Come decodificare il payload della decisione KYB.

Primi passi

Funzionalità

Profili aziendali

Riferimento

Console

Webhook KYB: eventi, payload e firma HMAC

Catalogo degli eventi

Eventi a livello di sessione

Eventi delle entità aziendali

Struttura del payload

`status.updated` per una sessione KYB

`data.updated` per una sessione KYB

`business.status.updated` e `business.data.updated`

Verifica della firma

Politica dei nuovi tentativi

Sottoscrizione

Prossimi passi

Riferimento dei webhook

Stati

Schema della risposta

​Catalogo degli eventi

​Eventi a livello di sessione

​Eventi delle entità aziendali

​Struttura del payload

​status.updated per una sessione KYB

​data.updated per una sessione KYB

​business.status.updated e business.data.updated

​Verifica della firma

​Politica dei nuovi tentativi

​Sottoscrizione

​Prossimi passi

Riferimento dei webhook

Stati

Schema della risposta

Catalogo degli eventi

Eventi a livello di sessione

Eventi delle entità aziendali

Struttura del payload

`status.updated` per una sessione KYB

`data.updated` per una sessione KYB

`business.status.updated` e `business.data.updated`

Verifica della firma

Politica dei nuovi tentativi

Sottoscrizione

Prossimi passi