Webhooks

Webhook é um mecanismo de integração orientado a eventos. Em vez de um sistema externo consultar a Konviva de tempos em tempos para descobrir se algo mudou, é a própria Konviva que avisa o sistema externo assim que o evento acontece. Quando o evento ocorre, por exemplo, uma matrícula finalizada ou um certificado disponível, a Konviva faz automaticamente uma chamada HTTP para o endereço (URL) informado pelo cliente e envia os dados desse evento.

A área de Webhooks, em Configurações > Integrações > Webhooks, permite cadastrar essas integrações. Cada webhook reúne:

• o evento da Konviva que dispara o envio;

• o tipo de ação, que define o que a Konviva faz quando o evento ocorre (no caso da Chamada HTTP, enviar os dados ao sistema externo);

• o método da chamada HTTP e a URL de destino, fornecida e formatada pelo cliente;

• os headers, que podem conter as informações de autenticação exigidas pelo sistema externo, como tokens e chaves;

• o body, com os dados do evento enviados na chamada.

A mesma área também permite acompanhar o histórico de execuções de cada webhook e reenviar os eventos que falharam (Acompanhamento e indicadores).

Jornada de uso

A área de Webhooks permite configurar notificações automáticas para que a Konviva envie informações a um sistema externo quando determinados eventos ocorrerem no LMS.

O fluxo geral é:

1. Um evento ocorre na Konviva, por exemplo, uma matrícula é efetuada ou um certificado fica disponível.

2. O Webhook identifica o evento configurado.

3. A Konviva prepara uma requisição HTTP usando a URL, o método, os headers e o template de body configurados.

4. A requisição é enviada ao endpoint do cliente ou de outro sistema integrado.

5. A execução é registrada na área de Monitoramento de logs de execução.

6. Em caso de falha, o evento pode ser analisado e reenviado individualmente ou em lote, conforme as permissões e opções disponíveis no ambiente.

Como configurar e realizar cadastros

Consultando os webhooks cadastrados

Acesse o menu Configurações > Integrações > Webhooks. A tela exibe a listagem dos webhooks cadastrados, com paginação e seletor de itens por página (Exibir n itens).

Cadastrando um webhook

Passo 1: Iniciar o cadastro. Acesse o menu Configurações > Integrações > Webhooks e clique em Adicionar Webhook.

Passo 2: Informar o nome. Preencha o campo Nome, que identifica o webhook na listagem.

Passo 3: Selecionar o tipo de evento. No campo Tipo de evento, escolha o evento que vai disparar o webhook. Os tipos de evento exibidos dependem do perfil do usuário.

Passo 4: Definir o tipo de ação. No campo Tipo de ação, selecione Chamada HTTP.

Passo 5: Informar os dados da chamada. Selecione o Método da chamada (GET ou POST), informe a URL do sistema externo e, se o sistema exigir, preencha os Headers. Ao selecionar o método POST, o formulário exibe também o campo Template do Body, que deve ser preenchido com o corpo da chamada. Na URL, nos headers e no body, é possível usar as notações $ID, $LOG e $EVENT, conforme o alerta exibido no formulário, reproduzido após a tabela de campos.

Passo 6: Definir o status e salvar. Mantenha a chave Status ligada para que o webhook fique ativo e clique em Salvar. Para desistir do cadastro, clique em Cancelar.

Depois de salvar, acompanhe as primeiras execuções na página de logs (Acompanhamento e indicadores).

Tipos de evento disponíveis para o perfil Administrador:

Editando, ativando, inativando e excluindo

Na listagem, use os ícones da coluna Ações: o lápis para editar o webhook, a engrenagem (Monitoramento de logs) para abrir os logs de execução e a lixeira para excluí-lo. Para ativar ou inativar um webhook, edite-o e altere a chave Status.

Acompanhamento e indicadores

Monitoramento de logs de execução

É possível realizar o gerenciamento de logs e o reenvio de execuções de webhooks na interface de monitoramento de logs de execução, em Configurações > Integrações > Webhooks > Monitoramento de logs de execução. Na listagem de webhooks, use o ícone de engrenagem (Monitoramento de logs), na coluna Ações, do webhook que deseja acompanhar.

A interface exibe o histórico detalhado de execuções do webhook selecionado, com filtros específicos e a possibilidade de reenviar os eventos que falharam, inclusive em lote. Os resultados são exibidos com paginação e seletor de itens por página.

Filtrando as execuções

Ao acessar a página do webhook, é possível filtrar os resultados por período (da data de início até a data de fim) e/ou por estado (FINISHED_SUCCESS ou FINISHED_ERROR). Informe as datas, selecione o estado e clique em Buscar. Para restaurar a tela ao estado inicial, clique em Limpar Campos.

Consultando a Saída do Console

No campo Ações, clique em Saída do Console para visualizar o detalhamento da execução. A janela Log de Console mostra o número do log, o método, o evento, o ID do objeto enviado e o estado da execução, além da URL chamada e do campo Response. Use essa informação para entender o motivo de um erro antes de reenviar o evento. Para voltar à listagem, clique em Fechar.

Aplicando no negócio

Para que serve

Os dados de aprendizagem raramente ficam só na plataforma de treinamento: a empresa também precisa deles no sistema de gestão de pessoas, em painéis de BI ou em repositórios de documentos. Sem integração, alguém precisa levar essas informações de um sistema para o outro, e a informação chega tarde ou desatualizada. O webhook resolve esse problema porque a Konviva avisa o outro sistema no momento em que o fato acontece. Com ele, a empresa consegue:

• manter sistemas externos atualizados com matrículas efetuadas, concluídas, canceladas ou excluídas e com mudanças de status da matrícula;

• enviar a um sistema externo a informação de que o certificado do aluno está disponível;

• levar o resultado das avaliações de aprendizagem para os painéis e indicadores da empresa;

• reduzir o trabalho manual e o intervalo entre o fato e o registro dele nos demais sistemas;

• ter rastreabilidade: o histórico de execuções mostra o que foi enviado e o que falhou, e os eventos com erro podem ser reenviados.

Quando utilizar

Vale a pena usar quando outro sistema precisa saber logo que algo acontece na Konviva, por exemplo:

• o sistema de gestão de pessoas precisa registrar a conclusão de um treinamento obrigatório;

• o painel de BI deve acompanhar matrículas e resultados de avaliações sem carga manual de dados;

• o certificado emitido precisa ser guardado em outro repositório;

• a empresa tem um time técnico capaz de configurar o webhook e manter o sistema que recebe as chamadas.

Costuma não compensar quando:

• basta consultar os relatórios da Konviva de tempos em tempos, sem necessidade de atualização imediata em outro sistema;

• a empresa não tem time técnico para configurar e acompanhar a integração;

• o sistema externo não consegue receber chamadas HTTP.