> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Webhook KYB: eventi, payload e firma HMAC > Didit: eventi webhook KYB per sessioni e aziende, trigger, schemi del payload e verifica della firma HMAC. Da $2.00 per verifica, senza contratti. 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](https://docs.didit.me/it/management-api/webhook/list-destinations.md) 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](https://docs.didit.me/it/getting-started/kyb-registry-pricing.md) è 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](https://docs.didit.me/it/sessions-api/retrieve-session.md). ### Eventi delle entità aziendali | Evento | Quando viene inviato | | - | - | | `business.status.updated` | Lo stato della [entità aziendale](https://docs.didit.me/it/entities/businesses/overview.md) 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à](https://docs.didit.me/it/entities/webhooks.md) 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](https://docs.didit.me/it/integration/webhooks.md#struttura-del-payload). 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](https://docs.didit.me/it/business-verification/statuses.md). | | `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/`](https://docs.didit.me/it/sessions-api/retrieve-session), vedi lo [schema della risposta](https://docs.didit.me/it/business-verification/response-schema.md). | | `resubmit_info` | object | Presente quando `status` è `Resubmitted`. | ### `status.updated` per una sessione KYB ```json theme={null} { "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 } }`. ```json theme={null} { "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](https://docs.didit.me/it/integration/webhooks.md#verifica-della-firma) 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](https://docs.didit.me/it/integration/webhooks.md#politica-di-nuovo-tentativo) contiene la politica completa. ## Sottoscrizione Sottoscrivi gli eventi che ti interessano su una [destinazione webhook](https://docs.didit.me/it/management-api/webhook/create-destination.md): ```bash theme={null} 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 > [card] [Riferimento dei webhook](https://docs.didit.me/it/integration/webhooks.md) > > Destinazioni, firma, nuovi tentativi, schemi comuni. > [card] [Stati](https://docs.didit.me/it/business-verification/statuses.md) > > Riferimento degli stati di sessione e di funzionalità. > [card] [Schema della risposta](https://docs.didit.me/it/business-verification/response-schema.md) > > Come decodificare il payload della decisione KYB. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.