> ## 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.

# Aggiornare la configurazione dei webhook tramite API

> Con Didit cambi il webhook, ruoti il segreto condiviso, imposti la conservazione dei dati e dei modelli biometrici e gli host di ritorno Digital ID.



Prompt API per l'aggiornamento della configurazione webhook
        Copia il prompt negli appunti



      
      

\<pre>

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

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

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

Goal:
\- Change application-level settings: the legacy webhook URL and version, the application secret, the data-retention and biometric-template retention policy, the Digital ID wallet return hosts, or the allowed origins of the hosted flow.

Behavior:
\- Partial update: send only the fields to change. The response is the full configuration, the same shape as GET /v3/webhook/.
\- webhook_url and webhook_version change the application-level (legacy) webhook only. Didit uses it only while the application has no enabled destination, and only for status.updated and data.updated. It does not create a destination, and the next create, update or delete of a destination replaces webhook_url. To receive webhooks, create a destination with POST /v3/webhook/destinations/ instead.
\- rotate_secret_key: true replaces the application-level secret_shared_key immediately. Destination secrets are not changed. Each call generates a new secret, so it is not idempotent.
\- data_retention_months (1 to 120, or null for no automatic deletion): user verification sessions older than this many 30-day months are deleted automatically. Business verification sessions are not affected.
\- face_retention_policy (delete_with_session or retain_until_user_deleted) and face_retention_days (1 to 3650). retain_until_user_deleted needs face_retention_days in the same request or already set.
\- allowed_return_hosts replaces the registered list: up to 20 bare hostnames such as app.example.com (no scheme, port, path or wildcard). Send [] to clear it.
\- allowed_domains replaces the list of web origins (for example https://app.example.com; http only for localhost) that the hosted verification flow may be embedded in and may send the user back to with a session callback: up to 50 entries of at most 300 characters. Send [] to remove the restriction. Server-to-server calls are not affected. An invalid entry returns 400 on allowed_domains.
\- Manage destinations with the /v3/webhook/destinations/ endpoints, not here. Never send an endpoints field to this call: it is not part of this contract.

Example call:
curl -X PATCH "https://verification.didit.me/v3/webhook/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365}'

What to read from the response:
\- The updated fields, and secret_shared_key when you rotated it: store the new value before you discard the response.

Failure modes:
\- 400: field errors, each field mapped to a list of messages, for example { "face_retention_days": ["A finite retention duration is required when face retention is enabled."] }. Nothing is changed.
\- 401: { "detail": "This API key has expired." }
\- 403: { "detail": "You do not have permission to perform this action." } or { "detail": "This API key has no write access to webhooks." }
\- 429: more than 300 write requests per minute with this key; wait for Retry-After.

Side effects:
\- Rotating the secret changes how deliveries to the legacy webhook_url are signed from then on, retries included.
\- A data_retention_months change applies to existing sessions too: every session older than the new window is deleted automatically, and that deletion is irreversible.
\- A face_retention_policy change applies to session deletions from then on; it creates or purges no existing biometric template.

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

\</pre>



      
      

Incolla in

> [!NOTE]
>
> `rotate_secret_key` ruota solo il segreto a livello di applicazione, che firma le consegne verso il `webhook_url` legacy. Ogni [destinazione webhook](https://docs.didit.me/it/management-api/webhook/list-destinations.md) firma con il proprio `secret_shared_key`, che questa chiamata non modifica.I campi di conservazione seguono la stessa policy che imposti in **Business Console → App Settings → Data retention**. Leggi [Conservazione dei dati](https://docs.didit.me/it/console/data-retention.md) prima di modificarli, in particolare la [conservazione del modello biometrico](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico). `allowed_return_hosts` è descritto in [Registra la tua destinazione di ritorno](https://docs.didit.me/it/standalone-apis/digital-id-wallets.md#registra-la-tua-destinazione-di-ritorno).`biometric_consent_mode` (`auto`, `always` o `never`) stabilisce quando il flusso di verifica chiede il consenso biometrico esplicito prima di acquisire un'immagine del volto. Vedi [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent.md).Per leggere prima i valori attuali, chiama [Leggi la configurazione webhook](https://docs.didit.me/it/management-api/webhook/get-config.md).


## OpenAPI

````yaml it/openapi-25.json PATCH /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/:
    patch:
      tags:
        - Webhook
      summary: Aggiorna la configurazione del webhook
      description: >-
        Aggiorna parzialmente le impostazioni a livello di applicazione: l'URL,
        la versione e il segreto del webhook legacy, i criteri di conservazione
        dei dati e dei modelli biometrici, e gli host di ritorno del wallet
        Digital ID. Invia solo i campi da modificare; la risposta contiene la
        configurazione completa, con la stessa struttura di `GET /v3/webhook/`.
        Le destinazioni non sono gestite qui: per crearle, aggiornarle ed
        eliminarle usa gli endpoint `/v3/webhook/destinations/`, e non inviare
        un campo `endpoints` a questo endpoint. Una modifica a
        `data_retention_months` si applica anche alle sessioni esistenti, e le
        sessioni che elimina non possono essere ripristinate; leggi prima
        [Conservazione dei
        dati](https://docs.didit.me/it/console/data-retention). Una chiave API
        con restrizioni di ambito richiede `webhooks: write`.
      operationId: update_webhook_config
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Invia solo i campi da modificare. Le destinazioni non vengono
                gestite qui.
              properties:
                webhook_url:
                  type: string
                  format: uri
                  nullable: true
                  maxLength: 2000
                  description: >-
                    URL del webhook legacy a livello di applicazione. Didit lo
                    usa solo quando l'applicazione non ha alcuna destinazione
                    abilitata, e solo per `status.updated` e `data.updated`. Non
                    crea una destinazione, e la successiva creazione,
                    aggiornamento o eliminazione di una destinazione lo
                    sostituisce. Per ricevere webhook, crea invece una
                    destinazione con `POST /v3/webhook/destinations/`.
                webhook_version:
                  type: string
                  enum:
                    - v1
                    - v2
                    - v3
                  description: Versione del payload del `webhook_url` legacy.
                rotate_secret_key:
                  type: boolean
                  default: false
                  description: >-
                    `true` sostituisce immediatamente la `secret_shared_key` a
                    livello di applicazione con un nuovo valore casuale; il
                    nuovo valore è presente nella risposta. I segreti di
                    destinazione non vengono modificati. Ogni chiamata con
                    `true` genera un nuovo segreto, pertanto non è idempotente.
                capture_method:
                  type: string
                  enum:
                    - MOBILE
                    - MOBILE_AND_DESKTOP
                  description: >-
                    Impostazione legacy dell'applicazione. Il flusso di verifica
                    non la legge.
                data_retention_months:
                  type: integer
                  nullable: true
                  minimum: 1
                  maximum: 120
                  description: >-
                    Intervallo di eliminazione automatica in mesi (un mese
                    equivale a 30 giorni), oppure `null` per nessuna
                    eliminazione automatica. Una modifica si applica anche alle
                    sessioni esistenti: ogni sessione di verifica degli utenti
                    più vecchia del nuovo intervallo viene eliminata
                    automaticamente, e tale eliminazione è irreversibile.
                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. `retain_until_user_deleted`
                    richiede `face_retention_days` nella stessa richiesta o già
                    impostato. Una modifica si applica alle eliminazioni di
                    sessioni da quel momento in poi; non crea né elimina alcun
                    modello biometrico esistente.
                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`.
                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).
                allowed_return_hosts:
                  type: array
                  maxItems: 20
                  description: >-
                    Sostituisce l'intero elenco di host di ritorno del wallet
                    Digital ID. Solo hostname semplici, come ad esempio
                    `shop.example.com`: nessuno schema, porta, percorso o
                    carattere jolly. I valori vengono convertiti in minuscolo e
                    i duplicati vengono rimossi. Invia `[]` per cancellare
                    l'elenco.
                  items:
                    type: string
                    maxLength: 253
                allowed_domains:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    maxLength: 300
                  description: >-
                    Sostituisce l'intero elenco delle origini consentite.
                    Origini (ad esempio `https://app.example.com`; `http` solo
                    per `localhost`) in cui il flusso di verifica ospitato può
                    essere incorporato e a cui può reindirizzare l'utente con
                    una callback di sessione. Le chiamate server-to-server non
                    sono interessate. Un elenco vuoto indica nessuna
                    restrizione. Didit memorizza ciascuna origine in lettere
                    minuscole senza una porta predefinita. Una voce non valida
                    genera un errore `400` su `allowed_domains`. Invia `[]` per
                    rimuovere la restrizione.
                  example:
                    - https://app.example.com
            examples:
              Enable biometric template retention:
                value:
                  face_retention_policy: retain_until_user_deleted
                  face_retention_days: 365
                  biometric_consent_mode: auto
              Rotate the legacy secret:
                value:
                  rotate_secret_key: true
              Set data retention:
                value:
                  data_retention_months: 24
              Register return hosts:
                value:
                  allowed_return_hosts:
                    - shop.example.com
                    - app.example.com
      responses:
        '200':
          description: >-
            La configurazione completa dopo l'aggiornamento, con la stessa
            struttura di `GET /v3/webhook/`. Se hai ruotato il segreto,
            memorizza la nuova `secret_shared_key` prima di eliminare la
            risposta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookConfig'
              examples:
                Retention enabled:
                  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: retain_until_user_deleted
                    face_retention_days: 365
                    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'
        '400':
          description: >-
            Validazione non riuscita: ogni campo non valido è mappato su un
            elenco di messaggi e nulla viene modificato. Un body che non è JSON
            valido restituisce `{"detail": "JSON parse error - ..."}`.
          content:
            application/json:
              schema:
                type: object
                description: Ciascun campo non valido associato a un elenco di messaggi.
                additionalProperties:
                  type: array
                  items:
                    type: string
              examples:
                Retention days missing:
                  value:
                    face_retention_days:
                      - >-
                        A finite retention duration is required when face
                        retention is enabled.
                    biometric_consent_mode: auto
                Retention window out of range:
                  value:
                    data_retention_months:
                      - Ensure this value is less than or equal to 120.
                Invalid return host:
                  value:
                    allowed_return_hosts:
                      - >-
                        'https://shop.example.com' is not a hostname. Register
                        the bare host (e.g. shop.example.com): no scheme, port,
                        path or wildcard.
                Invalid choice:
                  value:
                    face_retention_policy:
                      - '"forever" is not a valid choice.'
        '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 write:
                  value:
                    detail: This API key has no write 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 300 richieste di scrittura
            (POST, PATCH, PUT, DELETE) 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 (300).
              schema:
                type: integer
                example: 300
            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-write
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Messaggio di errore di facile lettura.
              examples:
                Throttled:
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X PATCH 'https://verification.didit.me/v3/webhook/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{"face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365}'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.webhooks.update_config(
                face_retention_policy="retain_until_user_deleted",
                face_retention_days=365,
                biometric_consent_mode="auto",
            )
            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.updateConfig({
              face_retention_policy: "retain_until_user_deleted",
              face_retention_days: 365,
              biometric_consent_mode: "auto",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.WebhooksUpdateConfigParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.webhooks().updateConfig(WebhooksUpdateConfigParams.builder()
                    .faceRetentionPolicy(WebhooksUpdateConfigParams.FaceRetentionPolicy.of("retain_until_user_deleted"))
                    .faceRetentionDays(365L)
                    .biometricConsentMode(WebhooksUpdateConfigParams.BiometricConsentMode.of("auto"))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->webhooks->updateConfig([
                'face_retention_policy' => 'retain_until_user_deleted',
                'face_retention_days' => 365,
                'biometric_consent_mode' => 'auto',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.webhooks.update_config(
              face_retention_policy: "retain_until_user_deleted",
              face_retention_days: 365,
              biometric_consent_mode: "auto"
            )
            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.UpdateConfigAsync(new
            WebhooksUpdateConfigParams

            {
                FaceRetentionPolicy = new WebhooksUpdateConfigParamsFaceRetentionPolicy("retain_until_user_deleted"),
                FaceRetentionDays = 365,
                BiometricConsentMode = new WebhooksUpdateConfigParamsBiometricConsentMode("auto"),
            });

            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.