Vai al contenuto principale
POST
curl
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

Sono accettate anche le famiglie di eventi Investigator (investigator.*) e Authentication (auth.*). Ogni evento e il relativo payload sono elencati in Webhooks. Set di sottoscrizione comuni:
Per esempi di payload e codice di firma, consulta la guida ai webhook.

Autorizzazioni

x-api-key
string
header
obbligatorio

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.

Corpo

application/json
label
string
obbligatorio

Nome di facile lettura visualizzato in Console → Webhooks. Aiuta a distinguere le destinazioni quando ne hai diverse (ad es. "Prod", "Staging mirror").

Maximum string length: 255
url
string<uri>
obbligatorio

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.

Maximum string length: 2000
enabled
boolean
predefinito:true

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
enum<string>

Versione dello schema del payload che Didit invierà. v3 è il formato attuale/consigliato; le versioni precedenti vengono mantenute per retrocompatibilità con le integrazioni legacy.

Opzioni disponibili:
v1,
v2,
v3
subscribed_events
enum<string>[]

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.

Minimum array length: 1

Nome dell'evento webhook supportato. Usa queste stringhe esatte in subscribed_events; i valori non supportati vengono rifiutati.

Opzioni disponibili:
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
Esempio:

Risposta

Destinazione creata. secret_shared_key è il segreto di firma HMAC: conservalo ora.

uuid
string<uuid>

Identificatore stabile della destinazione. Da usare come {destination_uuid} nelle chiamate successive.

label
string
url
string<uri>
enabled
boolean
webhook_version
enum<string>
Opzioni disponibili:
v1,
v2,
v3
secret_shared_key
string

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
string

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
string<date-time> | null

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). null quando non si è verificata alcuna rotazione nelle ultime 24 ore.

subscribed_events
enum<string>[]

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.

Minimum array length: 1

Nome dell'evento webhook supportato. Usa queste stringhe esatte in subscribed_events; i valori non supportati vengono rifiutati.

Opzioni disponibili:
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
Esempio:
created_by_email
string | null

Email del membro della Business Console che ha creato la destinazione. null per una destinazione creata con una chiave API.

created_by_name
string | null

Nome del membro della Business Console che ha creato la destinazione. null per una destinazione creata con una chiave API.

created_at
string<date-time>
updated_at
string<date-time>
health_status
enum<string>

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.

Opzioni disponibili:
healthy,
degraded,
failing
failing_streak
integer

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
string<date-time> | null

Data e ora del primo tentativo fallito dell'attuale failing_streak. null quando failing_streak è 0.

last_success_at
string<date-time> | null

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
enum<string>

Ambiente dell'applicazione proprietaria della destinazione.

Opzioni disponibili:
live,
sandbox
summary
object

Metriche di consegna per gli ultimi metrics_window_days (30) giorni. last_delivery_at è il tentativo più recente, a prescindere da quando è stato effettuato.

Ultima modifica il 7 novembre 2026