Webhooks de notificação

Editar online

Os webhooks de notificação são um recurso altamente versátil em IBM® Verify. Eles permitem que um administrador configure um terminal para receber um conjunto selecionado de dados de eventos em tempo real. Qualquer evento gerado no Verify pode ser propagado para o webhook configurado, o que permite que o Verify interaja com sistemas externos de maneira orientada a eventos.

Os usos comuns desta capacidade podem incluir os seguintes usos.

Rastreamento de tentativas de login de um usuário
Manter um CRM externo ou diretório de usuários atualizado com as mudanças no Cloud Directory
detectando novos dispositivos de Autenticação de diversos fatores
Encaminhando eventos para um SIEM

Para obter informações sobre cargas úteis de eventos, consulte Tipos de eventos e cargas úteis.

O administrador pode configurar um webhook de notificação com um conjunto de interesses. Esse conjunto de interesses decide quais eventos são enviados de Verify para o sistema externo.

Os webhooks de notificação são de alto volume. Quando sob carga, o Verify publica muitos eventos. O sistema externo deve estar preparado para receber um nível de carga correspondente. Tempos de resposta rápidos dos terminais de webhook configurados pelo administrador são essenciais quando os webhooks de notificação são usados em fluxos de usuário.

Configurando

Consulte a documentação da API para obter a estrutura completa do objeto de configuração do webhook. Esta seção se concentra na parte de interesses de um webhook de notificação.

O arquivo JSON de configuração do webhook contém uma propriedade notification. Essa propriedade é um objeto JSON aninhado que contém todas as opções de configuração específicas da notificação. A propriedade interests é definida dentro deste objeto notification. Quando um evento é gerado, ele é verificado em relação a cada elemento na propriedade interests. Se algum elemento dentro da propriedade interests for avaliado como uma correspondência, o evento será enviado para o destino do webhook. Os interesses são verificados em ordem, portanto, em casos de uso de alto desempenho, colocar a correspondência mais ampla em primeiro lugar é o método mais eficiente.

Um interesse consiste em dois campos, um name aliado e uma lista de clauses. Essas cláusulas decidem se o interesse é uma correspondência. Os clauses são unidos com uma operação AND e somente se todos corresponderem é que o interesse é atendido. Uma cláusula consiste em três campos:

key: É usado para determinar onde inspecionar, no evento, para descobrir se esta cláusula corresponde. Ele deve ser um nome de propriedade JSON. key pode ser usado para avaliar chaves de nível superior ou chaves dentro do objeto data de um evento. Ao referenciar o objeto data, a notação de ponto JSON é usada. Por exemplo, data.action.
value: Value é o valor esperado do campo que está sendo inspecionado.
operation: Indica se uma correspondência sobre esta cláusula faz com que o evento seja included ou excluded.

Por exemplo, em um cenário em que os eventos de autenticação são o principal interesse e você deseja filtrar as autenticações que ocorrem por meio da federação, use essas cláusulas.

Key: event_type, Value: authentication, Operation: include

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

Essas cláusulas se tornam a avaliação lógica.

event_type É authentication E data.subtype NÃO federation

Exemplos

O código a seguir é um exemplo completo da propriedade notification em uma configuração de webhook para atender a vários cenários.

Todos os eventos de autenticação não federados

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

Detecção de reprodução

O campo id de um evento permanece consistente para o tempo de vida daquele evento. Seja em uma chamada de webhook ou nos dados do evento que são recuperados da API de eventos. Este valor id também é usado como o valor no cabeçalho X-Webhook-ID para notificação webhooks.

Correio de notificação não entregue

É possível configurar um webhook para registrar quando uma notificação não foi entregue com êxito ao webhook.

Um administrador pode reconciliar as entregas com falha usando a API de mensagens não entregues do webhook de notificação, juntamente com a API de eventos. Estas cartas mortas registradas contêm o ID da notificação não entregue e o momento da notificação. Para visualizar a notificação não entregue, um administrador pode utilizar o valor ID para consultar a API de eventos para um valor de evento único diretamente. Os timestamps de vários eventos podem ser usados para recuperar uma gama de eventos e, em seguida, usar os IDs para filtrá-los no cliente.

Reconciliação de carta morta

Um mecanismo automatizado existe que tenta a reentrega de cartas mortas para o webhook configurado. Essas tentativas de reconciliação são identificáveis pela presença do valor "deadletter": true na carga útil.

Você pode acionar a reconciliação de dead-letter de duas maneiras:

Manualmente, por uma chamada para a API de flush.
Automaticamente, quando um webhook de notificação está mostrando um bom estado de saúde.
- Configure a configuração para especificar com que frequência ocorre essa reconciliação automatizada. Veja a documentação da API para obter detalhes.
- A API manual ainda pode ser usada para acionar uma reconciliação independentemente da configuração.

Uma API de status pode ser usada para verificar se um webhook está executando uma reconciliação e o progresso atual da reconciliação. Veja a documentação da API para obter detalhes. Apenas o resultado da execução da reconciliação é mantido por webhook. Esses resultados são mantidos por 7 dias ou até que uma outra reconciliação seja executada.

Se uma tentativa de reentrega de uma notificação falhar durante a reconciliação, então a reconciliação será encerrada. O limite de tempo duro nas reconciliações é de 2 horas. Se todas as cartas mortas não forem escancaradas dentro desse tempo, mais reconciliações devem ser executadas.