Webhook di notifica

Modifica online

I webhook di notifica sono una funzionalità altamente flessibile in IBM® Verify. Consentono a un amministratore di configurare un endpoint per ricevere una serie selezionata di dati evento in tempo reale. Qualsiasi evento che viene generato in Verify può essere propagato al webhook configurato, che consente a Verify di interagire con i sistemi esterni in modo basato sugli eventi.

Gli utilizzi comuni di questa funzionalità potrebbero includere i seguenti utilizzi.

Tracciamento dei tentativi di collegamento su un utente
Mantenere aggiornato un CRM esterno o una directory utente con le modifiche in Cloud Directory
Rilevamento di nuove unità MFA
Inoltro di eventi a un SIEM

Per informazioni sui payload degli eventi, vedere Tipi di eventi e payload.

L'amministratore può configurare un webhook di notifica con una serie di interessi. Questa serie di interessi decide quali eventi vengono inviati da Verify al sistema esterno.

I webhook di notifica hanno un volume elevato. Quando è sotto carico, Verify pubblica molti eventi. Il sistema esterno deve essere preparato per ricevere un livello di carico corrispondente. I tempi di risposta rapidi dagli endpoint webhook configurati dall'amministratore sono essenziali quando i webhook di notifica sono utilizzati nei flussi dell'utente.

Configurazione

Consultare la documentazione API per la struttura dell'oggetto di configurazione webhook completa. Questa sezione si concentra sulla sezione degli interessi di un webhook di notifica.

Il file JSON di configurazione webhook contiene una proprietà notification . Questa proprietà è un oggetto JSON nidificato che contiene tutte le opzioni di configurazione specifiche della notifica. La proprietà interests è definita all'interno di questo oggetto notification . Quando si verifica un evento, questo viene controllato rispetto a ogni elemento nella proprietà interests . Se un elemento all'interno della proprietà interests viene valutato come una corrispondenza, l'evento viene inviato alla destinazione webhook. Gli interessi vengono controllati in ordine, quindi nei casi di utilizzo ad alte prestazioni, mettere la corrispondenza più ampia al primo posto è il metodo più efficace.

Un interesse è costituito da due campi, un name amichevole e un elenco di clauses. Queste clausole decidono se l'interesse è una corrispondenza. Le clauses vengono unite con un'operazione AND e solo se tutte corrispondono è soddisfatto l'interesse. Una clausola è composta da tre campi:

key: Viene utilizzato per determinare dove, nell'evento da esaminare, rilevare se questa clausola corrisponde. Deve essere un nome di proprietà JSON. key può essere utilizzato per valutare chiavi o chiavi di livello superiore all'interno dell'oggetto data di un evento. Quando fa riferimento all'oggetto data , viene utilizzata la notazione del punto JSON. Ad esempio, data.action.
value: Value è il valore previsto del campo che viene ispezionato.
operation: Indica se una corrispondenza su questa clausola fa sì che l'evento sia included o excluded.

Ad esempio, in uno scenario in cui gli eventi di autenticazione sono l'interesse chiave e si desidera filtrare le autenticazioni che si verificano tramite la federazione, utilizzare queste clausole.

Key: event_type, Value: authentication, Operation: include

Key: data.subtype, Value: federation, Operation: exclude

Queste clausole diventano la valutazione logica.

event_type IS authentication AND data.subtype NON È federation

Esempi

Il seguente codice è un esempio completo della proprietà notification all'interno di una configurazione webhook per soddisfare vari scenari.

Tutti gli eventi di autenticazione non federati

"notifications": {
    "interests": [
      {
        "name": "Non-federation authentication events",
        "clauses": [
          {
            "key": "event_type",
            "value": "authentication",
            "operation": "include"
          },
          {
            "key": "data.subtype",
            "value": "federation",
            "operation": "exclude"
          }
        ]
      }
    ]
  }

Rilevamento ripetizione

Il campo id di un evento rimane congruente per la durata di tale evento. Se si trova in un callout webhook o nei dati evento richiamati dall'API degli eventi. Questo id viene utilizzato anche come valore nell'intestazione X-Webhook-ID per i webhook di notifica.

Lettere non note di notifica

Puoi configurare un webhook per registrare quando una notifica non è stata consegnata correttamente al webhook.

Un amministratore può riconciliare le consegne non riuscite utilizzando l'API di lettere inutilizzate del webhook di notifica, insieme all'API di eventi. Queste lettere non recapitate registrate contengono l'ID della notifica non recapitata e l'ora della notifica. Per visualizzare la notifica non consegnata, un amministratore può utilizzare il valore ID per interrogare direttamente l'API degli eventi per un singolo valore evento. Le date / ore di più eventi possono essere utilizzate per recuperare un intervallo di eventi e quindi utilizzare gli ID per filtrarli sul client.

Riconciliazione di lettere non recapitabili

Esiste un meccanismo automatizzato che tenta la ridistribuzione di lettere non recapitate al webhook configurato. Questi tentativi di riconciliazione sono identificabili dalla presenza del valore "deadletter": true nel payload.

È possibile attivare la riconciliazione dei messaggi non recapitabili in due modi:

Manualmente, da una chiamata all'API di scaricamento.
Automaticamente, quando un webhook di notifica mostra un buono stato di integrità.
- Impostare la configurazione per specificare la frequenza con cui si verifica questa riconciliazione automatizzata. Per i dettagli, consultare la documentazione API.
- L'API manuale può ancora essere utilizzata per attivare una riconciliazione indipendentemente dalla configurazione.

Un'API di stato può essere utilizzata per controllare se un webhook sta eseguendo una riconciliazione e l'avanzamento corrente della riconciliazione. Per i dettagli, consultare la documentazione API. Solo il risultato dell'esecuzione della riconciliazione viene conservato per webhook. Questi risultati vengono conservati per 7 giorni o fino a quando non viene eseguita un'altra riconciliazione.

Se un tentativo di riconsegna di una notifica non riesce durante la riconciliazione, la riconciliazione viene terminata. Il limite di tempo difficile per le riconciliazioni è di 2 ore. Se tutte le lettere non vengono cancellate entro tale periodo di tempo, è necessario eseguire ulteriori riconciliazioni.