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 um Participante conclui um Conteúdo ou recebe um certificado, 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, ou edite um token já existente (veja Tokens da API de integração).
- Na lista de permissões (escopos) do token, marque Webhooks (gerenciar).
- Salve o token.
Um token sem essa permissão que tente gerenciar webhooks recebe uma recusa de acesso. 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.
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, “matrícula concluída” ou “certificado emitido”) e os dados relacionados: a matrícula, a sala, o conteúdo e o participante. 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.
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.