Vai al contenuto principale
I webhook degli avvisi inviano gli alert del tuo team a un endpoint HTTPS di tua proprietà. Usali per alimentare uno strumento di reperibilità, una coda di ticket o la tua dashboard operativa. I webhook degli avvisi sono separati dai webhook di verifica. I webhook di verifica inviano alla tua applicazione i risultati di sessioni, entità e transazioni. I webhook degli avvisi segnalano al tuo team che qualcosa richiede attenzione: una verifica in attesa di revisione, un pagamento non riuscito, un incidente di servizio. Hanno un payload, un segreto di firma, una firma e una pianificazione dei nuovi tentativi propri.

Configurare una destinazione

Configuri i webhook degli avvisi nella Business Console, non tramite API. I membri che possono gestire le impostazioni dell’organizzazione possono aggiungere, modificare e testare le destinazioni.
1

Aggiungi la destinazione

In Impostazioni dell’organizzazione > Notifiche del team, aggiungi una destinazione Webhook degli avvisi con l’URL del tuo endpoint. L’URL deve usare https:// e puntare a un indirizzo pubblico.
2

Conserva il segreto di firma

Didit mostra il segreto di firma completo, che inizia con whsec_, una sola volta. Conservalo subito: in seguito la console mostra solo i suoi ultimi quattro caratteri.
3

Instrada gli alert verso di essa

L’aggiunta di una destinazione non invia ancora nulla. Aggiungi la destinazione alle regole di instradamento degli alert che vuoi che riceva.
4

Invia un test

Fai clic su Invia test per inviare un alert alert.test e verifica che il tuo endpoint lo accetti.
Un’organizzazione può avere fino a 25 destinazioni in Notifiche del team. Solo le attività nell’ambiente di produzione raggiungono una destinazione. Gli alert relativi a verifiche in sandbox, verifiche aziendali (KYB), transazioni e riscontri AML non vengono mai inviati a essa.

Tipi di alert

Payload

Ogni alert è una richiesta POST con un corpo JSON. Didit invia il corpo come JSON compatto con le chiavi ordinate. Questo esempio è formattato per la lettura:
data contiene sempre:
  • event: la chiave dell’evento, per esempio session_in_review.
  • label e value: a cosa si riferisce l’alert, per esempio Session e #1042.
Alcuni tipi di alert aggiungono chiavi a data:
  • alert.billing.autorefill_failed aggiunge paused, un booleano che vale true quando la ricarica automatica è sospesa finché non aggiorni la carta.
  • alert.service.degraded e alert.service.recovered aggiungono service, status, incident_id, service_name, state, affected, country_name, started_at, resolved_at, duration_minutes, title e body. status vale degraded o down in alert.service.degraded, e recovered in alert.service.recovered. service usa le chiavi di servizio di GET /v3/status/, e incident_id corrisponde a un id di incidente in quella risposta.
Gli alert non includono mai dati personali degli utenti finali o dati dei loro documenti. Identificano una sessione, una transazione o un altro elemento tramite il suo numero e rimandano a esso nella console. Ignora i valori di webhook_type e le chiavi di data che non riconosci, così le nuove non interrompono il tuo endpoint.

Intestazioni della richiesta

Verifica la firma

X-Signature-V2 è l’HMAC-SHA256 codificato in esadecimale della stringa <X-Timestamp>.<raw body>, utilizzando come chiave il segreto di firma della tua destinazione.
  • Usa il segreto completo esattamente come te lo ha mostrato Didit, incluso il prefisso whsec_.
  • Firma i byte grezzi della richiesta così come li hai ricevuti. Analizzare il JSON e serializzarlo di nuovo può modificare i byte e far fallire il controllo.
  • Confronta le firme in tempo costante.
  • Rifiuta una richiesta il cui X-Timestamp si discosta di più di 5 minuti dal tuo orologio. Didit firma ogni tentativo, inclusi i singoli nuovi tentativi, con un timestamp nuovo, quindi questa finestra non rifiuta mai un nuovo tentativo legittimo.
  • Rispondi a un controllo fallito con 400. Una risposta 401, 403, 404 o 410 contrassegna la destinazione per la riconnessione (vedi Nuovi tentativi).
I webhook degli alert non sono firmati come i webhook di verifica. L’intestazione si chiama anch’essa X-Signature-V2, ma la stringa firmata è diversa, e i webhook degli alert non inviano né X-Signature né X-Signature-Simple. Non riutilizzare il verificatore del tuo webhook di verifica.

Node.js (Express)

Python (Flask)

Ruota il segreto di firma

Ruoti il segreto sulla destinazione in Notifiche del team. Didit mostra il nuovo segreto una sola volta e firma con esso ogni tentativo successivo, inclusi i nuovi tentativi degli alert creati prima della rotazione. Il vecchio segreto smette di funzionare immediatamente. Non c’è alcun periodo di sovrapposizione e nessuna intestazione contiene una firma creata con il segreto precedente. Distribuisci il nuovo segreto sul tuo endpoint non appena lo ruoti.

Nuovi tentativi

Didit considera consegnata qualsiasi risposta 2xx. Ogni tentativo attende fino a 5 secondi la tua risposta e non segue i reindirizzamenti. Didit effettua un nuovo tentativo di invio dell’alert dopo un timeout, un errore di connessione, una risposta 5xx, oppure una risposta 408, 425 o 429. Effettua fino a 5 nuovi tentativi, nell’arco di circa 24 ore: Ogni altra risposta è definitiva, inclusa qualsiasi risposta 3xx e qualsiasi altra risposta 4xx. Per un test inviato con Invia test viene effettuato un solo tentativo e non viene mai ritentato. Una risposta 401, 403, 404 o 410 contrassegna anche la destinazione per la riconnessione: la console la mostra con lo stato Ricollega. Lo stesso vale per un URL che si risolve in un indirizzo privato o altrimenti bloccato al momento dell’invio da parte di Didit. Didit continua a inviare i nuovi alert alla destinazione e questa torna attiva alla consegna riuscita successiva o quando aggiorni il suo URL. Notifiche recenti in Notifiche del team elencano ogni consegna con il suo esito, e da lì puoi ritentare una consegna non riuscita.

Correlati

Ultima modifica il 7 novembre 2026