> ## 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. # Configurazione dei webhook: API > Leggi con l'API Didit le impostazioni webhook: URL e segreto legacy, destinazioni, eventi, conservazione dei dati e host di ritorno wallet. Prompt API per ottenere la configurazione dei webhook Copia il prompt negli appunti \

\`Read my Didit application's webhook configuration through the Management API.

Endpoint:
GET https://verification.didit.me/v3/webhook/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs webhooks: read.

Goal:
\- Get every setting that controls how Didit sends webhooks for my application, plus the data-retention policy and the Digital ID wallet return hosts, in one call. Use it to audit the setup or to show the current configuration in a back office.

Behavior:
\- Didit delivers webhooks to webhook destinations (/v3/webhook/destinations/). Each destination has its own url, webhook_version, secret_shared_key and subscribed_events.
\- webhook_url, webhook_version and secret_shared_key at the top level are the application-level (legacy) webhook. Didit uses them only while the application has no enabled destination, and then only for status.updated and data.updated.
\- Every create, update or delete of a destination sets webhook_url to the URL of the oldest enabled destination, or null when none is enabled.
\- API-key callers always receive the application secret and every destination secret in full.

Example call:
curl -X GET "https://verification.didit.me/v3/webhook/" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- endpoints: every destination, oldest first, with uuid, label, url, enabled, webhook_version, secret_shared_key and subscribed_events. Verify each webhook with the secret of the destination it was sent to.
\- available_events: every event type you can subscribe a destination to ({ value, label }).
\- webhook_url, webhook_version, secret_shared_key: the legacy webhook, only relevant when no destination is enabled.
\- data_retention_months (null means no automatic deletion), face_retention_policy and face_retention_days: the retention policy.
\- allowed_return_hosts: hosts a Digital ID wallet verification may send the person back to.
\- allowed_domains: web origins the hosted verification flow may be embedded in and may send the user back to; empty means no restriction.
\- capture_method: MOBILE or MOBILE_AND_DESKTOP. A legacy setting with no effect; capture options are set per workflow.

Failure modes:
\- 401: { "detail": "This API key has expired." }
\- 403: { "detail": "You do not have permission to perform this action." } for a missing key (a wrong, revoked or expired key gets 401); { "detail": "This API key has no read access to webhooks." } for a scoped key without webhooks: read.
\- 429: more than 600 GET requests per minute with this key; wait for Retry-After.

Side effects: none. This is a pure read, and the response contains signing secrets: never log it.

For the full integration shape, see /integration/integration-prompt.`

\
Incolla in Questo endpoint restituisce il webhook a livello di applicazione, introdotto prima che esistessero le destinazioni, insieme all'elenco delle destinazioni. Didit consegna i webhook alle tue [destinazioni webhook](https://docs.didit.me/it/management-api/webhook/list-destinations.md), ciascuna firmata con il proprio `secret_shared_key`. I campi di primo livello `webhook_url`, `webhook_version` e `secret_shared_key` vengono usati solo finché non è abilitata alcuna destinazione, e in tal caso solo per `status.updated` e `data.updated`.> [!WARNING] > > La risposta contiene tutti i segreti di firma della tua applicazione. Non inserirla nei log né nel codice lato client.Per modificare queste impostazioni, usa [Aggiorna la configurazione dei webhook](https://docs.didit.me/it/management-api/webhook/update-config.md). Per la verifica della firma e i payload, consulta la [guida ai webhook](https://docs.didit.me/it/integration/webhooks.md). Per i campi di conservazione dei dati, consulta [Conservazione dei dati](https://docs.didit.me/it/console/data-retention.md). ## OpenAPI ````yaml it/openapi-25.json GET /v3/webhook/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/: get: tags: - Webhook summary: Recupera configurazione webhook description: >- Restituisce le impostazioni webhook dell'applicazione in un'unica chiamata: ogni [destinazione webhook](https://docs.didit.me/it/management-api/webhook/list-destinations) con il rispettivo segreto di firma, i tipi di evento a cui una destinazione può iscriversi, l'URL webhook a livello di applicazione (legacy), la versione e il segreto, la politica di conservazione dei dati e dei modelli biometrici e gli host di ritorno del wallet Digital ID. Didit consegna i webhook alle destinazioni, ciascuno firmato con la propria `secret_shared_key`; i campi di primo livello `webhook_url`, `webhook_version` e `secret_shared_key` vengono utilizzati solo finché non è abilitata alcuna destinazione, e in tal caso unicamente per `status.updated` e `data.updated`. La risposta contiene segreti di firma, pertanto non includerla nei log né nel codice lato client. Una chiave API con ambito richiede `webhooks: read`. operationId: get_webhook_config parameters: [] responses: '200': description: La configurazione del webhook. content: application/json: schema: $ref: '#/components/schemas/WebhookConfig' examples: One destination: value: webhook_url: https://yourapp.com/webhooks/didit webhook_version: v3 secret_shared_key: dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA capture_method: MOBILE data_retention_months: 24 face_retention_policy: delete_with_session face_retention_days: null biometric_consent_mode: auto available_events: - value: status.updated label: Session status updated - value: data.updated label: Session data updated - value: user.status.updated label: User status updated - value: user.data.updated label: User data updated - value: business.status.updated label: Business status updated - value: business.data.updated label: Business data updated - value: activity.created label: Activity created - value: transaction.created label: Transaction created - value: transaction.status.updated label: Transaction status updated - value: travel_rule.status.updated label: Travel Rule Status Updated - value: workflow.compliance_changed label: Workflow Compliance Changed allowed_return_hosts: - shop.example.com endpoints: - uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA subscribed_events: - status.updated - data.updated created_at: '2026-01-04T08:00:00.000000Z' updated_at: '2026-04-22T14:09:11.523671Z' '401': description: >- La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`. content: application/json: schema: type: object properties: detail: type: string description: Messaggio di errore di facile lettura. examples: Expired key: value: detail: This API key has expired. '403': description: >- La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` content: application/json: schema: type: object properties: detail: type: string description: Messaggio di errore di facile lettura. examples: Missing or invalid key: value: detail: You do not have permission to perform this action. Scoped key without webhooks read: value: detail: This API key has no read access to webhooks. Outside the IP allowlist: value: detail: This API key can't be used from this IP address. '429': description: >- Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare. headers: Retry-After: description: Secondi da attendere prima di effettuare un nuovo tentativo. schema: type: integer minimum: 1 example: 30 X-RateLimit-Limit: description: Richieste consentite nell'intervallo di un minuto (600). schema: type: integer example: 600 X-RateLimit-Remaining: description: Richieste rimanenti nell'intervallo corrente. schema: type: integer example: 0 X-RateLimit-Reset: description: Ora Unix (secondi) in cui la finestra corrente si azzera. schema: type: integer example: 1792056120 X-RateLimit-Scope: description: Nome del budget superato. schema: type: string example: generic-get content: application/json: schema: type: object properties: detail: type: string description: Messaggio di errore di facile lettura. examples: Throttled: value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X GET 'https://verification.didit.me/v3/webhook/' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.retrieve_config() print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.retrieveConfig(); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.RetrieveConfig(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().retrieveConfig(); System.out.println(result); - lang: php label: PHP source: |- webhooks->retrieveConfig(); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.retrieve_config puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.RetrieveConfigAsync(); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookConfig: type: object description: >- Configurazione dei webhook a livello di applicazione, policy di conservazione e host di ritorno del wallet Digital ID, con ogni destinazione webhook. required: - webhook_url - webhook_version - secret_shared_key - capture_method - data_retention_months - face_retention_policy - face_retention_days - available_events - allowed_return_hosts - endpoints properties: webhook_url: type: string format: uri nullable: true description: >- URL del webhook a livello di applicazione (legacy). Didit invia le notifiche a questo URL solo se l'applicazione non ha destinazioni abilitate, e in tal caso invia solo `status.updated` e `data.updated`. Ogni operazione di creazione, aggiornamento o eliminazione di una destinazione lo imposta sull'URL della destinazione abilitata più vecchia, oppure su `null` se nessuna è abilitata. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Versione del payload del `webhook_url` legacy. Ciascuna destinazione ha il proprio `webhook_version`. secret_shared_key: type: string description: >- Segreto di firma a livello di applicazione (token URL-safe di 43 caratteri). Firma solo le consegne al `webhook_url` legacy; ciascuna destinazione firma con la propria `secret_shared_key`. I chiamanti autenticati tramite chiave API lo ricevono sempre per intero; gli utenti della Console privi dell'autorizzazione `read:webhooks` ricevono una stringa vuota. capture_method: type: string enum: - MOBILE - MOBILE_AND_DESKTOP description: >- Impostazione legacy dell'applicazione. Il flusso di verifica non la legge: le opzioni di acquisizione sono configurate per workflow. data_retention_months: type: integer nullable: true minimum: 1 maximum: 120 description: >- Finestra di eliminazione automatica. Le sessioni di verifica degli utenti create più di questo numero di mesi fa (un mese corrisponde a 30 giorni) vengono eliminate automaticamente e tale eliminazione è irreversibile. `null` indica che le sessioni non vengono mai eliminate automaticamente. Consulta [Conservazione dei dati](https://docs.didit.me/it/console/data-retention). face_retention_policy: type: string enum: - delete_with_session - retain_until_user_deleted description: >- Cosa succede all'embedding facciale di una sessione quando la sessione viene eliminata. `delete_with_session` (predefinito) lo elimina con la sessione. `retain_until_user_deleted` è l'opzione facoltativa per la [conservazione del modello biometrico](https://docs.didit.me/it/console/data-retention#conservazione-del-modello-biometrico): un modello biometrico privo di immagini collegato all'Utente viene gestito separatamente fino al termine del periodo di conservazione, all'eliminazione dell'Utente o alla sua eliminazione definitiva. face_retention_days: type: integer nullable: true minimum: 1 maximum: 3650 description: >- Periodo di conservazione, in giorni, dei modelli biometrici secondo `retain_until_user_deleted`. Obbligatorio quando tale criterio è impostato. biometric_consent_mode: type: string enum: - auto - always - never description: >- Quando il flusso ospitato e gli SDK nativi richiedono alla persona il consenso biometrico esplicito prima dell'acquisizione del volto. `auto` (predefinito) lo richiede solo quando si applica un trigger: uno stato dichiarato, l'IP della persona o l'emittente del documento d'identità si trova in Illinois, Texas o Colorado, oppure la persona sembra trovarsi negli Stati Uniti senza uno stato noto. `always` lo richiede a ogni persona il cui workflow acquisisce un volto. `never` non mostra mai il passaggio, e raccogli tu stesso il consenso prima del selfie. Ogni modifica viene registrata nel registro di audit. Consulta [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent). available_events: type: array description: >- Ogni tipo di evento a cui una destinazione può iscriversi, con un'etichetta visibile. items: type: object required: - value - label properties: value: $ref: '#/components/schemas/WebhookEvent' label: type: string description: Etichetta visualizzata, ad esempio `Session status updated`. allowed_return_hosts: type: array maxItems: 20 description: >- Hostname (corrispondenza esatta, solo HTTPS) a cui una verifica del wallet Digital ID autonoma può rimandare l'utente con il suo `return_url`. Anche il tuo dominio white label è sempre consentito. Consulta [Registra la tua destinazione di ritorno](https://docs.didit.me/it/standalone-apis/digital-id-wallets#registra-la-tua-destinazione-di-ritorno). items: type: string maxLength: 253 endpoints: type: array description: >- Ogni destinazione webhook dell'applicazione, dalla più vecchia alla più recente, ciascuna con il rispettivo segreto di firma. Qui in sola lettura: gestisci le destinazioni con gli endpoint `/v3/webhook/destinations/`. items: $ref: '#/components/schemas/WebhookConfigDestination' allowed_domains: type: array maxItems: 50 items: type: string maxLength: 300 description: >- Origini (ad esempio `https://app.example.com`; `http` consentito solo per `localhost`) in cui il flusso di verifica ospitato può essere incorporato e a cui può reindirizzare l'utente con un callback di sessione. Le chiamate server-to-server non sono interessate. Un elenco vuoto indica che non vi sono restrizioni. Didit memorizza ciascuna origine in lettere minuscole e senza porta predefinita. Una voce non valida genera un errore `400` su `allowed_domains`. example: - https://app.example.com WebhookEvent: type: string description: >- Nome dell'evento webhook supportato. Usa queste stringhe esatte in `subscribed_events`; i valori non supportati vengono rifiutati. enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready WebhookConfigDestination: type: object description: >- Una destinazione webhook così come elencata nella configurazione dei webhook, senza metriche di consegna. `GET /v3/webhook/destinations/{destination_uuid}/` aggiunge il relativo riepilogo di consegna. required: - uuid - label - url - enabled - webhook_version - secret_shared_key - subscribed_events - created_at - updated_at properties: uuid: type: string format: uuid description: ID della destinazione. label: type: string maxLength: 255 description: Nome leggibile dall'utente. url: type: string format: uri maxLength: 2000 description: Endpoint HTTPS a cui Didit invia gli eventi. enabled: type: boolean description: '`false` sospende le consegne verso questa destinazione.' webhook_version: type: string enum: - v1 - v2 - v3 description: Versione del payload inviata a questa destinazione. secret_shared_key: type: string description: >- Il segreto di firma di questa destinazione (token URL-safe di 43 caratteri). Verifica ogni webhook con il segreto della destinazione a cui è stato inviato. I chiamanti con chiave API lo ricevono sempre per intero; gli utenti della Console privi di `read:webhooks` ricevono una stringa vuota. subscribed_events: type: array uniqueItems: true description: >- Tipi di evento consegnati a questa destinazione. Vuoto se la destinazione è stata creata senza eventi, nel qual caso non riceve nulla. items: $ref: '#/components/schemas/WebhookEvent' created_at: type: string format: date-time updated_at: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.