> ## 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. # Creare destinazione webhook API > Registra una destinazione webhook Didit con versione, eventi sottoscritti e segreto di firma dedicato. Gestione webhook via API, a consumo. Prompt API per la creazione di una destinazione webhook Copia il prompt negli appunti \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

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

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

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

\
Incolla in Le destinazioni webhook ti permettono di inviare eventi Didit diversi a URL diversi. Ogni destinazione ha il proprio `secret_shared_key`, `webhook_version` e il proprio elenco `subscribed_events`.## Come funziona `subscribed_events``subscribed_events` è un array obbligatorio di nomi di evento esatti. Didit invia un webhook a questa destinazione solo quando il `webhook_type` del payload corrisponde a uno dei valori dell'array.- Includi almeno un evento. - Usa solo i nomi di evento supportati elencati di seguito. - Aggiungi ogni evento che vuoi ricevere; non esiste un valore jolly come `*` o `all`. - Per instradare aree di prodotto diverse verso sistemi diversi, crea più destinazioni con elenchi `subscribed_events` diversi.## Catalogo degli eventi| Evento | Sottoscrivi quando ti serve | | - | - | | `status.updated` | Lo stato di una sessione di Verifica degli utenti (KYC) o di Verifica aziendale (KYB) cambia. I payload KYB includono `session_kind: "business"` e `business_session_id`. | | `data.updated` | I dati di verifica della sessione vengono corretti o aggiornati dopo la creazione, ad esempio con modifiche del revisore ai dati KYC, di Prova di residenza o KYB. | | `user.status.updated` | Un'entità User cambia stato, ad esempio `ACTIVE`, `FLAGGED` o `BLOCKED`. | | `user.data.updated` | Il profilo, i contatori, i metadati, i documenti o i campi di verifica aggregati di un'entità User cambiano. | | `business.status.updated` | Un'entità Business cambia stato, ad esempio dopo una revisione manuale, i risultati KYB o un'azione di blocklist. | | `business.data.updated` | Il profilo, i contatori, i metadati, i campi di registrazione o i campi di verifica aggregati di un'entità Business cambiano. | | `activity.created` | Accettato in `subscribed_events` e coperto da **Try Webhook**, ma Didit al momento non lo invia per il traffico di produzione. | | `transaction.created` | Viene creata una transazione di Monitoraggio delle transazioni e la sua valutazione iniziale delle regole è completata. | | `transaction.status.updated` | Una transazione cambia stato dopo la valutazione delle regole, la revisione dell'analista, le azioni correttive, gli aggiornamenti del provider o le azioni da API o console; viene inviato anche una sola volta quando uno screening crypto ritentato in background si completa. | | `travel_rule.status.updated` | Uno scambio [Travel Rule](https://docs.didit.me/it/transaction-monitoring/travel-rule.md) cambia stato. | | `workflow.compliance_changed` | Lo stato di conformità di un workflow pubblicato cambia dopo una rivalutazione. | | `transaction_rule_suggestions.created` | Un'esecuzione di suggerimenti di regole propone nuove modifiche alle regole. |Sono accettate anche le famiglie di eventi Investigator (`investigator.*`) e Authentication (`auth.*`). Ogni evento e il relativo payload sono elencati in [Webhooks](https://docs.didit.me/it/integration/webhooks.md#tipi-di-evento).Set di sottoscrizione comuni:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```Per esempi di payload e codice di firma, consulta la [guida ai webhook](https://docs.didit.me/it/integration/webhooks.md). ## OpenAPI ````yaml it/openapi-25.json POST /v3/webhook/destinations/ 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/destinations/: post: tags: - Webhook summary: Crea destinazione webhook description: >- Crea una destinazione webhook. La risposta include il segreto di firma HMAC `secret_shared_key` generato automaticamente (leggibile anche in seguito tramite `GET /v3/webhook/destinations/{destination_uuid}/`). Invia sempre `subscribed_events` con almeno un evento (senza caratteri jolly): una lista esplicitamente vuota viene rifiutata con 400, mentre l'omissione del campo crea una destinazione non iscritta ad alcun evento, che non riceverà mai un webhook. La coppia `(application, url)` deve essere univoca tra le destinazioni dell'applicazione. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nome di facile lettura visualizzato in Console → Webhooks. Aiuta a distinguere le destinazioni quando ne hai diverse (ad es. "Prod", "Staging mirror"). url: type: string format: uri description: >- URL HTTPS che riceverà le richieste `POST`. Deve essere univoco tra le destinazioni dell'applicazione. Usa un endpoint stabile e protetto: Didit ritenta le consegne non riuscite secondo una pianificazione con backoff. maxLength: 2000 enabled: type: boolean default: true description: >- Quando è `false`, la destinazione viene salvata ma Didit non invierà alcun webhook ad essa. Utile per le configurazioni di staging che desideri mantenere in sospeso. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Versione dello schema del payload che Didit invierà. `v3` è il formato attuale/consigliato; le versioni precedenti vengono mantenute per retrocompatibilità con le integrazioni legacy. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Eventi da consegnare. Di fatto obbligatorio: un `[]` esplicito viene rifiutato con 400, e omettendo il campo si crea una destinazione senza abbonamenti che non riceve nulla. examples: session_updates: summary: Aggiornamenti sui dati e sullo stato della sessione value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Aggiornamenti del monitoraggio delle transazioni value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: Aggiornamenti delle entità utente e azienda value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- Destinazione creata. `secret_shared_key` è il segreto di firma HMAC: conservalo ora. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Identificatore stabile della destinazione. Da usare come `{destination_uuid}` nelle chiamate successive. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- Segreto di firma HMAC generato automaticamente e associato a questa destinazione (token URL-safe di 43 caratteri). Usalo per verificare le intestazioni di firma sui webhook in arrivo. Viene sempre restituito per intero a chi chiama tramite chiave API; gli utenti della Console necessitano dell'autorizzazione `read:webhooks`, altrimenti visualizzano una stringa vuota. secret_last4: type: string description: >- Ultimi quattro caratteri del segreto di firma attuale della destinazione, per consentirti di distinguere i segreti. Non sufficienti per verificare una firma. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Impostato per 24 ore dopo la rotazione del segreto di firma della destinazione nella Business Console. Fino a tale momento, ogni consegna alla destinazione include anche `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, generati con il segreto sostituito (vedi [Verifica della firma](/it/integration/webhooks#verifica-della-firma)). `null` quando non si è verificata alcuna rotazione nelle ultime 24 ore. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- Email del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API. created_by_name: type: string nullable: true description: >- Nome del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Stato della consegna. `failing`: 3 o più eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta riuscita della destinazione (vedere `failing_streak`). `degraded`: non in errore, ma un tentativo di consegna è fallito nelle ultime 24 ore e nessun tentativo successivo ha consegnato quell'evento; un nuovo tentativo o reinvio che lo consegna cancella questa condizione. `healthy`: nessuno dei due. Indipendente da `enabled`. Un tentativo fallito è quello a cui è stato risposto con HTTP 400 o superiore, o a cui non è stata data alcuna risposta. failing_streak: type: integer description: >- Quanti eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta positiva della destinazione, negli ultimi 30 giorni. I nuovi tentativi non vengono conteggiati e qualsiasi tentativo riuscito, inclusi nuovi tentativi o reinvii, interrompe la serie. `0` quando nessun evento ha fallito dall'ultimo successo. failing_since: type: string format: date-time nullable: true description: >- Data e ora del primo tentativo fallito dell'attuale `failing_streak`. `null` quando `failing_streak` è `0`. last_success_at: type: string format: date-time nullable: true description: >- Data e ora dell'ultima risposta della destinazione a una consegna con uno stato HTTP inferiore a 400, negli ultimi 30 giorni. `null` se non ha risposto in tale intervallo. environment: type: string enum: - live - sandbox description: >- Ambiente dell'applicazione proprietaria della destinazione. summary: type: object description: >- Metriche di consegna per gli ultimi `metrics_window_days` (30) giorni. `last_delivery_at` è il tentativo più recente, a prescindere da quando è stato effettuato. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- Durata in giorni dell'intervallo coperto dalle altre metriche di riepilogo. Sempre `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- Validazione non riuscita — solitamente un URL duplicato, `subscribed_events` mancante o non valido, oppure un nome di evento sconosciuto. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: Limite di frequenza superato; rallenta e riprova. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) 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.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) 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.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- Filtro degli eventi per questa destinazione webhook. Didit consegna solo i webhook il cui tipo di evento corrisponde esattamente a uno di questi valori — non esiste un abbonamento con caratteri jolly. Quando viene inviato, l'elenco deve contenere almeno un evento valido (un `[]` esplicito viene rifiutato con 400); una destinazione il cui elenco è vuoto (campo omesso alla creazione) non riceve nulla. In caso di aggiornamento, l'elenco viene sostituito per intero, mai unito. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated 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 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.