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