Webhooks
Avisos automáticos ao seu sistema quando algo acontece na plataforma: eventos, filtros, dados pessoais, histórico de entregas e falhas do destino.
Um webhook avisa o seu sistema quando algo acontece na plataforma. Por exemplo: um aluno concluiu uma aula, e a Cademí manda um aviso ao seu CRM. O webhook é o endereço do seu sistema (ou do Zapier, Make, n8n) que recebe esses avisos. Você configura tudo em Configurações → Webhooks. O formato de cada evento, para quem vai programar o receptor, está em https://cademi.dev/webhooks.
A ideia em um minuto
- Um evento é um fato que a Cademí registra na conta: um aluno ganhou acesso, foi aprovado numa prova, concluiu uma aula.
- Um webhook é um endereço inscrito em alguns eventos.
- Uma entrega é cada aviso que a Cademí manda a esse endereço.
Uma entrega de webhook não tem relação com uma entrega de vendas (Entregas).
A regra mais importante: o webhook ouve o acesso, não a venda. Uma venda do gateway não é um evento. O que chega ao seu sistema é o acesso que a venda produziu.
A tela tem duas abas:
- Endpoints: a lista dos webhooks. Cada linha mostra Evento / escopo, Endpoint e Status. O Status é Ativo ou Inativo, e você troca na própria linha. Os filtros Eventos e Status e a busca por endereço recortam a lista.
- Histórico: as entregas.
Há dois formatos de webhook:
- Cademí v3, o formato atual. Um webhook recebe vários eventos, cada um com o seu filtro, e cada envio vai assinado. É o que Novo webhook cria, e é o que este artigo explica.
- Legado v2 e Legado v1 (descontinuado), o formato antigo, com um evento por webhook. Serve só para um sistema que já recebe esse formato. Novo webhook legado cria um. Numa integração nova, use Novo webhook.
Criar um webhook
- Abra Configurações → Webhooks.
- Clique em Novo webhook.
- Em Para onde enviar, cole o Endpoint: o endereço do seu sistema, começando com https://.
- Se quiser, preencha a Descrição. Ela ajuda a reconhecer o webhook na lista e não vai no envio.
- Em Quando enviar, marque os eventos.
- Nos eventos que aceitam filtro, preencha o bloco Enviar só quando, que aparece logo abaixo. Vazio quer dizer "sempre que acontecer".
- Em O que cada envio leva, escolha o nível de dados pessoais (veja abaixo).
- Confira o Resumo, ao lado.
- Clique em Criar webhook.
- Na janela Segredo de assinatura, copie e guarde o segredo.
O segredo não aparece de novo. Com ele, o seu servidor confere que cada envio saiu da Cademí.
Para escolher os eventos, a tela tem duas abas:
- Jornada do aluno agrupa os momentos mais usados.
- Sincronização (avançado) lista todos os eventos da plataforma, por grupo, com o nome técnico. É para quem mantém outro sistema sempre em dia com a Cademí.
Buscar evento procura nas duas abas. Marcar todos e Desmarcar valem por grupo. Ver exemplo do envio mostra o que chega ao seu endereço, com dados de exemplo.
Os momentos da jornada do aluno
| Momento | Eventos |
|---|---|
| Cadastro | Aluno criado, Tags do aluno atualizadas, Campo personalizado atualizado |
| Acesso | Acesso liberado, Primeiro acesso, Acesso suspenso ou reativado, Acesso revogado, Acesso restaurado |
| Progresso | Curso iniciado, Aula concluída, Marco de progresso atingido, Progresso atualizado, Curso concluído |
| Provas | Prova concluída, Tentativa de prova reaberta |
| Certificados | Certificado emitido, Certificado revogado |
| Termos | Termo aceito |
| Pontos | Pontos creditados, Pontos ajustados |
| Atendimento | Chamado aberto, Chamado respondido, Chamado encerrado, Dúvida enviada, Dúvida respondida, Comentário enviado, Comentário respondido |
Atenção: é aqui que mais acontece erro. Cada evento tem um momento certo:
- Venda: o aluno recebe uma entrega e dispara Acesso liberado. O reembolso, o atraso e o pagamento de volta disparam Acesso suspenso ou reativado.
- Curso iniciado é a primeira aula concluída, não o acesso concedido. Para boas-vindas, use Aluno criado ou Primeiro acesso.
- Prova concluída dispara com aprovado ou reprovado. Para só um deles, filtre por Resultado da prova.
- Chegar a 100% não emite certificado. Certificado emitido só acontece quando alguém pede o certificado.
- O aviso de um comentário ou de uma dúvida não leva o texto que o aluno escreveu.
- Um administrador que vê a área como aluno de teste não gera nenhum desses eventos.
Os filtros
| Filtro | Nos eventos de | O que faz |
|---|---|---|
| Produto | progresso, provas, certificados, comentários e dúvidas | Um produto só, ou Qualquer produto |
| Aula e Prova | aula concluída, comentários, dúvidas e provas | Aparecem depois que você escolhe o produto. Você pode marcar várias |
| Resultado da prova | Prova concluída | Aprovado ou reprovado, Só aprovado ou Só reprovado |
| Ao chegar em | Marco de progresso atingido | 50%, 75% ou 90% |
| A partir de | Progresso atualizado | Uma porcentagem mínima. Depois que o aluno passa dela, toda aula seguinte dispara de novo. Para um aviso único, prefira o marco |
| Tipo de cadastro | Aluno criado | Cadastro pago ou Cadastro gratuito. O cadastro pelo Google e o da importação não são nem um nem outro. Com uma das duas escolhas, eles ficam de fora |
| Oferta | Acesso liberado | Só os acessos daquela entrega: os compradores desta oferta |
| Tag que o aluno ganhou | Tags do aluno atualizadas | Só quando aquela tag é adicionada. Uma tag que o aluno já tinha, ou que só foi removida, não dispara |
| Campo personalizado e Só quando ficar preenchido | Campo personalizado atualizado | Um campo. Se quiser, só quando ele deixa de estar vazio |
| Termo | Termo aceito | Um termo específico |
| Pontos por | Pontos creditados | O motivo dos pontos (aula, marco, prova, comentário) |
Quantos dados pessoais vão
O nível vale para todos os eventos do mesmo webhook.
| Nível | O que chega | Use quando |
|---|---|---|
| Só identificadores, sem dados pessoais (o padrão) | Os códigos do aluno e do que aconteceu, sem nome nem contato. O seu sistema busca o resto pela API | O receptor consulta o aluno, ou só precisa contar |
| Com dados pessoais mascarados | Os códigos, mais nome, e-mail e telefone parcialmente escondidos. Ainda é dado pessoal | A ferramenta precisa de uma pista de quem é, sem guardar o contato real |
| Completo, com dados pessoais | Os dados como estão no cadastro | O sistema precisa escrever, ligar ou faturar para o aluno. E ele é confiável para guardar esses dados |
Só um administrador autorizado a ver os dados dos alunos pode escolher o nível completo. Se o webhook inclui chamados, ele precisa ver também o atendimento. A Cademí confere cada envio contra quem criou o webhook. Se essa pessoa perde a autorização, os envios saem mascarados até ela voltar, e a tela avisa.
A página de um webhook
Clique na linha para abrir o webhook. No alto ficam o status, Ver histórico deste webhook, Enviar teste e Gerar novo segredo.
O painel de saúde mostra:
- o Último envio entregue;
- as Últimas 24 horas: entregues, falhas e na fila;
- o estado do Endereço: Recebendo normalmente, Envios pausados por falhas seguidas ou Testando o endereço de novo.
Enviar teste manda agora ao seu endereço um exemplo do evento escolhido. O exemplo tem dados fictícios, vai assinado com o segredo atual e é marcado como teste. Você vê o Status HTTP, o Tempo e a Resposta. O teste não entra no histórico e não conta para a saúde do webhook.
Gerar novo segredo cria um segredo novo e o mostra uma vez. O anterior continua assinando por 24 horas. Assim, você troca o segredo no receptor sem parada.
Histórico
A aba Histórico lista as entregas dos últimos 60 dias, em quatro visões: Todos, Sucesso, Pendentes e Com falha. Só Com falha tem contagem, porque é a fila que pede ação. O filtro Webhook recorta por destino.
Cada linha mostra Enviado em, Evento, Código (a resposta do destino), Endpoint e Status. Se houve mais de uma tentativa, a linha mostra o número.
| Status | O que quer dizer |
|---|---|
| Na fila | Esperando o próximo envio |
| Enviando | Saindo agora |
| Sucesso | O destino recebeu e respondeu com sucesso |
| Erro | O destino recusou de um jeito que não adianta repetir (endereço inexistente ou bloqueado). Só sai de novo por reenvio manual |
| Esgotado | As tentativas acabaram sem sucesso. Só sai de novo por reenvio manual ou ao reativar o webhook |
| Cancelado | Não vai mais ser enviada. O webhook foi desativado ou excluído antes de ela sair, ou o sistema abandonou o endereço |
Clique na linha para abrir Detalhes da entrega. A janela mostra a Resposta do destino e o Payload enviado. Nas entregas que falharam, ela tem o botão Reenviar. Reenviar coloca a mesma entrega na fila de novo. Ele não cria um evento novo.
Quando o destino falha
Se o endereço não aceita uma entrega, a Cademí tenta de novo sozinha:
- A espera entre as tentativas cresce de 2 minutos até 6 horas.
- A Cademí tenta cerca de 10 vezes, ou por 72 horas.
- Se o destino pede para esperar, ou está instável, o adiamento não gasta tentativa.
- Uma recusa definitiva não é repetida.
O caminho de uma entrega até o status final, com as novas tentativas e as voltas à fila:
Carregando diagrama…
Com o webhook Inativo, a entrega espera na fila e não é cancelada. Reativar e reenviar devolve só o que esgotou ou foi cancelado pela desativação nas últimas 48 horas. Uma entrega cancelada porque o webhook foi excluído não volta.
| Situação | O que acontece | Como volta |
|---|---|---|
| Você deixa o webhook Inativo | As entregas ficam retidas. Esperar não é falha | Ligue de novo e elas saem |
| O endereço falha em vários envios diferentes em 24 horas | O sistema desativa o webhook e cancela o que ainda esperava. Ele avisa por e-mail os administradores que gerenciam webhooks | Na página do webhook, Reativar ou Reativar e reenviar as últimas 48 horas |
| O endereço fica muito tempo sem responder | Todo webhook que aponta para esse endereço é desativado. Isso vale também em outras contas que o usam | Reative cada um |
A lista e a página do webhook mostram o motivo da desativação. Salvar o webhook não o reativa. Corrija o endereço, se for o caso, e use Reativar. Nada com mais de 48 horas volta sozinho.
Bom saber
O receptor precisa tolerar repetição.
Reenvios e reativações entregam o mesmo evento de novo. Se o seu sistema não reconhece o evento repetido, um CRM cria dois contatos e uma ferramenta de e-mail escreve duas vezes ao aluno.
Excluir cancela o que esperava.
Excluir um webhook cancela as entregas pendentes. As concluídas ficam no histórico. O suporte pode recuperar o webhook excluído.
Mudar o nível não reescreve o passado.
Um nível mais rico vale para o que acontece depois. O que já foi preparado sai como estava.
Webhook não é histórico.
Ele pode ser pausado e desligado. Para olhar para trás ou montar um relatório, use a lista de eventos da API, não um webhook numa planilha.
Diamante.
As mensagens de etapa dos funis Diamante ficam nas telas do Diamante (Funis Diamante), não aqui.
Antigo e novo no mesmo sistema.
Um webhook legado e um webhook v3 apontados para a mesma ferramenta avisam o mesmo momento duas vezes, com dois nomes.
Perguntas frequentes
Quero avisar meu CRM a cada compra.
No momento Acesso, marque Acesso liberado e Acesso suspenso ou reativado. Se for uma entrega específica, filtre por Oferta. O webhook ouve o acesso, não a venda.
O evento aconteceu e nada chegou.
Abra o Histórico e procure a entrega:
- Na fila: a plataforma ainda vai tentar.
- Erro ou Esgotado: veja a Resposta do destino, corrija e reenvie.
- Nenhuma entrega: o evento não está marcado, ou o filtro excluiu o caso.
Se a lista mostra o webhook desativado, reative.
Meu webhook foi desativado sozinho.
O endereço falhou em vários envios seguidos. Corrija o destino e teste com Enviar teste. Depois, clique em Reativar e reenviar as últimas 48 horas para recuperar o que ficou para trás.
Recebi o mesmo aviso duas vezes.
Um reenvio ou uma reativação entrega o mesmo evento de novo. O seu sistema precisa reconhecer o evento repetido.
Chaves de API
A credencial que outro sistema usa para ler e mudar dados da sua plataforma pela API: criar a chave, dar permissões, guardar o segredo e revogar.
Código personalizado
Blocos de código na área do aluno e no login: Google Analytics, Tag Manager, Pixel, Active Campaign, WhatsApp, Push Alert e CSS ou JavaScript próprios.