Como configurar o Webhook?

O que é um Webhook?

A tradução literal para Webhook é “gancho na web”. Webhooks criam um tipo de conexão entre dois sistemas, para que um sistema possa receber informações do outro assim que uma determinada ação ocorrer.

Quais Status o Webhook cadastrado no portal do unico | check envia notificação?

2 - Em divergência

3 - Concluído

4 - Cancelado

5 - Erro

Para os outros status não são enviadas notificações no Webhook.

Como cadastrar mais de um Webhook?

É necessário criar mais APIKeys, cada credencial só pode ser atrelada a um Webhook. Lembrando que o Webhook cadastrado receberá qualquer notificação de processos que utilizaram aquela APIKey na chamada de Createprocess e CreateMessage.

 O que é notificação de alterações de score suspeito?

É uma configuração em que se opta por receber notificações quando um CPF que anteriormente foi positivado, seja removido ou enviado para o suspeito, ou estava negativado, e devido a uma reanálise se tornou positivo. Importante ressaltar que somente um Webhook pode estar configurado para receber notificações de alteração de score suspeito.

Como configurar um Webhook no portal da Unico?

O caminho para configuração sempre será o mesmo para Webhooks com ou sem autenticação, o que mudará são os campos preenchidos dentro do painel de configuração de Webhooks. Abaixo está o caminho a ser seguido para acessar a tela de configuração de Webhooks:

Passo 1: Entre no portal e no menu principal acesse Menu de Configurações;

Passo 2: Na página de configurações acesse Menu de Integração;

Passo 3: Na página de integração acesse Menu de Webhooks;

Passo 4: Clique em cima de um Webhook para alterar um existente, ou clique no botão “Novo Webhook” para criar um novo;

Passo 5: Faça todas alterações necessárias e salve o Webhook;

Passo 6: Volte para o Menu de integrações e acesse o menu de APIKeys;

Passo 7: Clique na APIKey desejada para abrir as configurações dela e no campo chamado Webhook, escolha o Webhook que deseja atrelar a essa APIKey (caso já tenha feito essa configuração, as etapas 6 e 7 são desnecessárias)

 

Modelos de Autenticação Disponíveis

Disponibilizamos atualmente 4 possibilidades de configurações dos Webhooks. Modelo sem autenticação, com a utilização de um Secret, com a utilização de campos chaves adicionais no Header de resposta, ou autenticação via JWT.

 

Configurando Webhook Sem Autenticação

Os campos abaixo são comuns a todos os modelos de autenticação. Tratando-se do modelo sem autenticação, podemos nos limitar apenas a eles, conforme descrição abaixo:

1.png

Descrição (Obrigatório): campo para nomear o Webhook

Request URI (Obrigatório): campo para inserir a URI de Callback

Status (Obrigatório): se o Webhook está ativo ou inativo

Notificar alteração de score suspeito (Obrigatório): opção ou não pelo envio de alertas de alteração de score suspeito. Lembrando que apenas um Webhook pode ter este campo configurado como “SIM”.

Tempo de tentativas em minutos (Obrigatório): espaço de tempo entre as tentativas de comunicação com o Webhook em um mesmo processo.

Número máximo de tentativas (Obrigatório): quantidade máxima de tentativas de comunicação para um mesmo processo.

Tipo de autenticação: na Unico hoje é possível ter ou não autenticação via JWT, para o modelo sem autenticação deve ser escolhido a opção “nenhuma”.

Configurando Webhook utilizando Secret:

Ao preencher o campo Secret, o valor preenchido neste campo será enviado em todas as notificações do Webhook no campo Authorization no header.

2.png

Configurando Webhook - Adicionando Headers para a resposta do Webhook

É possível adicionar headers para que seja realizada uma autenticação com campos específicos para o endpoint de callback. Para adicionar esses campos clique no botão “Adicionar” e preencha os campos "Chave" e "Valor". É possível adicionar quantos campos forem necessários.

3.png

OBS: Os campos do Header podem ser adicionados e ao mesmo tempo o Secret ser utilizado.

Configurando o Webhook com autenticação JWT:

Descrição dos campos

Para a configuração do Webhook com autenticação com JWT é preciso preencher todos os campos utilizados na configuração do Webhook sem autenticação.

Além disso, o campo “Tipo de autenticação” deve estar preenchido com o valor “JWT Bearer” conforme a imagem abaixo:

4.png

Ao preencher o campo com esse valor, aparecerá na tela novos campos para serem preenchidos dentro da área chamada Requisição do Token.

URL da Requisição (Obrigatório): URL em que a aplicação da unico deverá chamar para a obtenção do token.

Certificado: deve ser anexado o certificado gerado pelo cliente. Somente as extensões .CRT e .PEM serão aceitas.

PrivateKey: deve ser incluída a chave privada gerada pelo cliente. Somente as extensões .KEY e .PEM serão aceitas.

Tempo de expiração do Token (Obrigatório): deve ser informado o intervalo de tempo para ser gerado um novo token de autenticação.

Sub: caso seu Webhook necessite do campo Sub, informá-lo aqui. Utilizado no método RFC 7523.

Ver: caso seu Webhook necessite do campo Ver, informá-lo aqui.

 

É possível também adicionar Headers na requisição do token com um processo de adição similar ao dos headers da requisição para a resposta do Webhook, porém esses headers só estarão presentes na requisição do token.

E por último, existe a opção de adicionar um valor ao campo body para a geração do token (Não obrigatório).

Método RFC 7523

Caso opte por utilizar uma requisição assinada, em Headers para a resposta do Webhook será possível preencher o valor do header com as tags abaixo.

  • {{signature}}
  • {{nonce}}
  • {{timestamp}}
  • {{algorithm}}

Ex.: Chave = X-Signature | Valor = {{signature}} - Substituiremos o valor desse header pela requisição assinada. É permitido para o cliente customizar os campos acima.

Nesse método, os campos Certificado, Privatekey, Sub e Ver são obrigatórios.

Método RFC 7519

Nesse método os campos Certificado, Privatekey, Sub e Ver não são obrigatórios e o campo body deve ser preenchido com um usuário e senha para autenticação e geração do token, conforme exemplo abaixo:

 "user":"USR_UNICO",

  "password":"senha1234"

}

 

IMPORTANTE: verifique se o firewall não bloqueia IP externo para gerar token, os servidores da unico estão distribuídos globalmente e com redundância em mais de uma região.

Esse artigo foi útil?
Usuários que acharam isso útil: 0 de 0