Webhooks da API de integração
Um webhook é um aviso automático que a Eduvem envia para outro sistema assim que algo acontece - sem que esse sistema precise ficar perguntando “e agora, mudou algo?”. Com webhooks, quando a matrícula de um Participante muda de status, ele recebe um certificado ou completa uma trilha, a Eduvem “empurra” essa informação na hora para o endereço que a sua equipe de integração indicar (o RH, um BI, um sistema interno).
É a alternativa “em tempo real” à consulta periódica: em vez de o seu sistema perguntar de tempos em tempos o que mudou, a Eduvem avisa sozinha na hora em que muda.
Para quem é este recurso
Seção intitulada “Para quem é este recurso”Configurar webhooks envolve duas pessoas com papéis diferentes:
- O administrador da instituição (você) libera a permissão em um token de API. É o que este artigo cobre.
- A sua equipe de integração (quem programa) usa esse token para registrar os endereços que vão receber os avisos e para tratar cada aviso recebido. Essa parte técnica está na documentação da API.
Liberando a permissão de webhooks em um token
Seção intitulada “Liberando a permissão de webhooks em um token”Os webhooks são gerenciados com os mesmos tokens de API usados pelo resto da integração - não há uma credencial separada. A capacidade de gerenciar webhooks fica atrás de uma permissão específica, que vem desligada por padrão: webhooks:manage.
- No painel administrativo, abra a aba Integrações da instituição.
- Crie um novo token de API (veja Tokens da API de integração). Se a integração já tem um token, você também pode ligar a permissão nele pelo botão Editar permissões da lista de tokens, sem gerar um token novo.
- Na lista de permissões (escopos) do token, marque Webhooks (gerenciar) e Relatórios (leitura) - inscrever-se em qualquer evento exige as duas permissões juntas.
- Confirme com OK e copie o valor do token exibido - ele não será mostrado de novo.
Um token sem a permissão Webhooks que tente gerenciar webhooks recebe uma recusa de acesso. Criar ou atualizar uma assinatura também exige a permissão Relatórios (leitura) junto com Webhooks - sem ela, a chamada é recusada mesmo com Webhooks marcado; listar, testar e excluir assinaturas não exigem Relatórios. Conceder a um token permissão de ler participantes e matrículas não concede, sozinho, a permissão de webhooks - ela precisa ser marcada explicitamente. Como sempre, conceda a um token só o que a integração realmente usa.
Os avisos ficam vinculados ao token que criou ou atualizou por último o cadastro do webhook. Se você remover a permissão Relatórios (leitura) desse token, ou excluí-lo, os webhooks dele param de enviar avisos e passam a aparecer como tokenRevoked; os eventos desse período não são reenviados depois. Para retomar, a equipe de integração deve reativar o webhook usando um token que tenha as duas permissões. Ao trocar um token por outro, crie o novo, reative cada webhook com ele e só então exclua o antigo.
O que os avisos carregam (visão geral)
Seção intitulada “O que os avisos carregam (visão geral)”Cada aviso é uma notificação assinada, enviada para o endereço que a sua equipe registrar, informando o evento (por exemplo, “mudança de status da matrícula”, “certificado emitido” ou “trilha concluída”) e os dados relacionados: a matrícula, a sala, o conteúdo e o participante. Um aviso de trilha concluída é diferente: ele carrega o participante e a trilha (identificador e nome), sem matrícula, sala ou conteúdo - uma trilha reúne várias salas, então o aviso não está ligado a uma única delas. Tudo é isolado por instituição - um aviso só carrega dados da instituição dona do token.
O envio do CPF dentro do aviso segue a configuração de perfil da sua instituição: se o campo CPF não estiver habilitado no perfil, ele não é enviado.
Quando a pessoa tem um externalId (o código do sistema de RH carregado pela sincronização de pessoas), o bloco da pessoa do aviso traz também person.externalId; sem ele, a chave não aparece e o aviso fica como antes. Veja Documentação da API.
Detalhes técnicos ficam na documentação da API
Seção intitulada “Detalhes técnicos ficam na documentação da API”O registro dos endereços que recebem os avisos, o catálogo completo de eventos, a verificação da assinatura de segurança, a política de novas tentativas e o monitoramento das entregas são feitos pela equipe de integração e estão descritos na documentação da API. Encaminhe esse material a quem for programar a integração.