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. Essas mensagens não entregues registradas contêm o ID da notificação não entregue e a hora em que ela foi enviada. Para visualizar a notificação não entregue, um administrador pode usar o valor do ID para consultar diretamente a API de eventos em relação a um único evento. Os carimbos de data/hora de vários eventos podem ser usados para recuperar um intervalo de eventos e, em seguida, utilizar os IDs para filtrá-los no cliente.

Reconciliação de mensagens não entregues

Existe um mecanismo automatizado que tenta reenviar as mensagens com falha 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 iniciar a reconciliação de mensagens não entregues de duas maneiras:
  • Manualmente, por meio de uma chamada à API de flush.
  • Automaticamente, quando um webhook de notificação indica um status de bom funcionamento.
    • Defina a configuração para especificar a frequência com que essa reconciliação automática ocorre. Consulte a documentação da API para obter mais detalhes.
    • A API manual ainda pode ser usada para iniciar uma reconciliação, independentemente da configuração.
É possível usar uma API de status para verificar se um webhook está executando uma reconciliação e qual é o andamento atual dessa reconciliação. Consulte a documentação da API para obter mais detalhes. Por webhook, é mantido apenas o resultado da execução da reconciliação. Esses resultados são mantidos por 7 dias ou até que seja executada outra reconciliação.

Se uma tentativa de reenvio de uma notificação falhar durante a reconciliação, a reconciliação será encerrada. O prazo máximo para as reconciliações é de 2 horas. Se todas as mensagens não entregues não forem eliminadas dentro desse prazo, será necessário executar mais reconciliações.