Como configurar o Webhook?

Seguir

O que é um Webhook?

A tradução literal para webhook é um “gancho na web”. Em resumo, 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.

 

Posso cadastrar mais de um Webhook?

Sim, é possível cadastrar mais de um webhook. Para isso é necessário criar mais APIKeys, pois cada APIKey só pode ser atrelada a um webhook. Lembrando que o webhook cadastrado naquela APIKey receberá toda 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 o Menu de Configurações;
Passo 2: Na página de configurações acesse o Menu de Integração;
Passo 3: Na página de integração acesse o 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. Em se tratando do modelo Sem Autenticação, podemos nos limitar apenas a eles, conforme descrição abaixo:

 

portal1webhook.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 1 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.


portal2webhook.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 basta clicar no botão “Adicionar” e preencher os campos Chave e Valor. É possível adicionar quantos campos forem necessários.

 

portal3webhook.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:

portal4webhook.png

 

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

Abaixo está a descrição de cada campo:

 

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:

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

Caso ainda tenha dúvidas, entre em contato conosco (canais de atendimento).

Estamos à disposição para atendê-los! 😉

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

Comentários

0 comentário

Artigo fechado para comentários.