# 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](https://help.cademi.cloud/pt/vendas/entregas.md)).

**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

1. Abra **Configurações > Webhooks**.
2. Clique em **Novo webhook**.
3. Em **Para onde enviar**, cole o **Endpoint**: o endereço do seu sistema, começando com https://.
4. Se quiser, preencha a **Descrição**. Ela ajuda a reconhecer o webhook na lista e não vai no envio.
5. Em **Quando enviar**, marque os eventos.
6. Nos eventos que aceitam filtro, preencha o bloco **Enviar só quando**, que aparece logo abaixo. Vazio quer dizer "sempre que acontecer".
7. Em **O que cada envio leva**, escolha o nível de dados pessoais (veja abaixo).
8. Confira o **Resumo**, ao lado.
9. Clique em **Criar webhook**.
10. 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:

```mermaid
stateDiagram-v2
    accTitle: O caminho de uma entrega de webhook
    accDescr: Quando um evento marcado acontece, a entrega entra na fila e sai. Se o destino aceita, fica em Sucesso. Uma falha passageira a devolve à fila para nova tentativa. Uma recusa definitiva leva a Erro, e o fim das tentativas ou do prazo leva a Esgotado. Desativar ou excluir o webhook antes do envio leva a Cancelado. Reenviar, ou reativar e reenviar, devolve a entrega à fila.
    state "Na fila" as Fila
    state "Enviando" as Enviando
    state "Sucesso" as Sucesso
    state "Erro" as Erro
    state "Esgotado" as Esgotado
    state "Cancelado" as Cancelado
    [*] --> Fila: Evento marcado acontece
    Fila --> Enviando
    Enviando --> Sucesso: Destino aceita
    Enviando --> Fila: Falha passageira, nova tentativa
    Enviando --> Erro: Recusa definitiva
    Enviando --> Esgotado: Fim das tentativas ou do prazo
    Fila --> Cancelado: Webhook desativado pelo sistema ou excluído
    Erro --> Fila: Reenviar
    Esgotado --> Fila: Reenviar, ou reativar e reenviar
    Cancelado --> Fila: Reativar e reenviar
```

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](https://help.cademi.cloud/pt/conteudo/funis-diamante.md)), 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.